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Unicode Functions (OS/2 Warp) 

Second Edition (October 1997) 

This document describes the OS/2 Warp Universal Language Support (ULS) functions. These functions 
provide APIs and data types to support internationalization of applications. 

This document is broken up into four major sections: 

• Locale and Character Classification Functions 

• Codepage Conversion Functions 

• ULS Data Types 

• Notices 
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Universal Language Support Functions 

Internationalized applications are required to operate in a variety of environments based on some territory, 
language, and/or cultural definition. These environments are identified by a locale, an object which 
encapsulates culturally specific infonnation. The locale identifies the culture, language, and territory that it 
supports. 

UniCompleteUserLocale 

UniCompleteUserLocale is used to finish a locale modification. This API is called after one or more 
UniSetLocaleltem calls to cause the new user defined locale file to be saved. 

Format 


((include <unidef.h> 


int UniCompleteUserLocale 
(void) 
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Parameters 
None required. 

Returns 

return value (int) - returns 

UniCompleteUserLocale returns one of the following values: 
ULSSUCCESS 

Successful completion; overridden items have been written to a file. 
ERROROPENFAILED 

DosOpen failed to open the locale file. 
ERRORACCESSDENIED 

DosWrite failed due to denied access. 

ULSNOMEMORY 

Insufficient memory to create a buffer for writing the new locale. 


Remarks 

UniCompleteUserLocale is used to complete the process of defining a new locale or modifying an existing 
locale. An application will use the UniQueryLocale API's and UniSefUserLocaleltem API to take an existing 
locale definition and customize that definition to form a new locale. When the customization process is 
complete, the UniCompleteUserLocale API is invoked to save the results as a new locale. 

The result of calling this API is that the locale is saved to disk as a new user locale or changes to an existing 
locale are saved to disk to represent the newly created locale. 

Related Functions 

• UniDeleteUserLocale 

• UniMakeUserLocale 

Example 


This example shows how to complete a user locale after modifying 
one or more locale items. 

#include <stdio.h> 

#include <unidef.h> 
int main (void) { 

LocaleObject locale_object = NULL; 

/* Array containing user locales */ 

UniChar *uniUsrLocales ; 

int rc = ULS_SUCCESS ; 

/-k'k'k-k-k-k'k-k-k-k-k-k'k-k'k'k'k'k'k-k-k-k-k'k-k-k-k-k'k'k-k'k'k'k'k-k-k-k-k'k'k-k-k-k-k'k'k'k'k'k'k-k-k-k-k'k-k-k-k-k-k'k'k'k'k j 

/* Assumes LANG environment variable set to a valid locale name, */ 
/* such as fr_FR */ 

/iciciciciciciciciciciciciciciciciciciciciciciciciciciciriririricicic-k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k-k'k'k'k'k'k'k'k'k'k J 

rc = UniCreateLocaleObject (UNI_UCS_STRING_PO INTER, 

(UniChar *)L"", &locale_object) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniCreateLocaleObj ect error: return code = %u\n", rc) ; 
return 1; 
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} 

/* allocate space for the user defined locales */ 
uniUsrLocales = (UniChar *) malloc (4096) ; 

/* Query the list of user defined locales available to modify */ 
rc = UniQueryLocaleList (UNI_USER_LOCALES , uniUsrLocales, 2048); 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniQueryLocaleList error: return code = %u\n", rc) ; 
return 1; 

} 


/* Change locale definition by calling UniSetUserLocaleltem to make 
locale item changes. 

*/ 


/* Write the current set of user locales to disk */ 
rc = UniCompleteUserLocale () ; 
if (rc ! = ULS_SUCCESS ) { 

printf ( "UniCompleteUserLocale error: return code = %u\n", rc) ; 
return 1; 

} 

return ULS SUCCESS; 


} 

UniCreateAttrObject 

UniCreateAttrObject creates an attribute object that is used to detennine character classifications. 

Format 


((include <unidef.h> 


int UniCreateAttrObject 

(const LocaleObject localeobject, const UniChar *AttrName, AttrObject *attr_object) 


Parameters 

locale object (const LocaleObject) 

Locale object created by a call to UniCreateLocaleObjectQ or NULL. 


AttrName (const UniChar *) 

A UniChar string that specifies the attribute names for which an attribute object should be created. 
Multiple attribute names are specified as a string of separate names. 
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attrobject (AttrObject *) 

An address that will receive a pointer to an attribute object upon successful completion of 
UniCreateAttrObj ect. 

Returns 

return value (int) - returns 

UniCreateLocaleObject returns one of the following values: 

ULS_SUCCESS 

Successful completion; attr object points to a valid attribute object. 

ULSJJNSUPPORTED 

The attribute name specified in AttrName is not supported by the localeobject. 

ULSNOMEMORY 

Insufficient memory to create the attribute object. 


Remarks 

UniCreateAttrObject allocates resources associated with an attribute defined in the LCCTYPE category of 
the locale indicated by the locale object argument. 

The locale object argument specifies a locale object handle returned by UniCreateLocaleObject. It should not 
be a NULL pointer. 

The AttrName argument specifies the attribute names for which an attribute object handle should be created. 
Multiple attribute names are specified as a string of space-separated names. 

When UniCreateAttrObject completes without errors, the attr object argument specifies a valid pointer to an 
attribute object. 

The attribute object pointer should be used in all subsequent calls to the UniQueryCharAttr. If the function 
result is other than ULS SUCCESS, the contents of the area pointed to by attr object are undefined. 

The following attribute names are the base POSIX attributes. All attribute names which can be specified in 
UniQueryCharAttr are allowed. Those attributes which start with underscore (_) or hash (#) may not be 
combined with other attributes. 

alnum 

True when alpha or digit is true. 

alpha 

True when upper or lower is true, or when none of cntrl, digit, punct, or space is true. 

blank 

True for the characters space and horizontal tab. 

cntrl 

True for any control character; the following attributes must be false: upper, lower, alpha, digit, xdigit, 
graph, print, and punct. 

digit 

True for the digits 0, 1, 2 3, 4, 5, 6, 7, 8, and 9. 

graph 

True for any character with the print attribute, except the space 
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character 

(Code element 0x0020). 

lower 

True for any character that is a lowercase letter and none of cntrl, digit, punct, or space is true. 

print 

True for upper, lower, alpha, digit, xdigit, punct, or any printing character including the space character 
(code element 0x0020). 

punct 

True for any printing character that is neither the space character (code element 0x0020) nor a character 
for which alnum is true. 

space 

True for any character that corresponds to a standard white-space character or is one of the set of 
white-space characters in the locale as indicated by the localeobject argument for which alnum is false. 
The standard white-space characters are the following: space, form feed, newline, carriage return, 
horizontal tab, and vertical tab. 

upper 

True for any character that is an uppercase letter and none of cntrl, digit, punct, or space is true. 

xdigit 

true for 0, 1,2, 3, 4, 5, 6, 7, 8, 9, A, B, C, D, E F, a, b, c, d, e, and f. 

Related Functions 

• UniQueryAttr 

• UniQueryChar 

• UniQueryCharAttr 

• UniQueryCharType 

Example 


This example shows how to create and use a character attribute object. 
#include <stdio.h> 


#include <unidef.h> 
int main (void) { 

LocaleObject locale_object = NULL; 


AttrObject 

int 

int 

UniChar 

/* 


attr_object = NULL; 

result = 0; 

rc = ULS_SUCCESS ; 

uni_char = L'a'; /* Unicode lowercase Latin letter a */ 

'k'k-k'k-k-k'k-k-k-k-k'k'k-k'k'k'k'k-k'k-k-k'k-k-k-k-k-k'k-k-k-k-k'k-k-k'k-k-k-k-k-k-k-k'k'k'k-k'k'k-k-k-k-k-k-k-k-k-k-k-k-k'k 


*/ 


/* Assumes LANG environment variable set to a valid locale name, */ 
/* such as fr_FR */ 

/iciciciciciciciciciciciririririciciciciciciciciciciciciriririricicicic-k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k J 


rc = UniCreateLocaleObject (UNI_UCS_STRING_POINTER, 

(UniChar *)L"", &locale_object) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniCreateLocaleObj ect error: return code = %u\n", rc) ; 
return 1; 


/* Create an alphabetic attribute object */ 
rc = UniCreateAttrObject (locale_object, 

(UniChar *)L"alpha", &attr_object) ; 

if (rc ! = ULS SUCCESS) { 
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printf ( "UniCreateAttrObject error: return code = %u\n", rc) ; 
return 1; 

} 

/* Make call to determine if character is alphabetic */ 
result = UniQueryCharAttr (attr_object, uni_char) ; 
if (result) 

printf ( "UniChar character %04X is alphabetic\n" , uni_char) ; 
else 

printf ( "UniChar character %04X is not alphabetic\n" , uni_char) ; 
return ULS SUCCESS; 


} 


UniCreateLocaleObject 

UniCreateLocaleObject creates a locale object. 

Format 


((include <unidef.h> 

int UniCreateLocaleObject 

(int LocaleSpecType, const void *LocaleSpec, LocaleObject *locale_object) 


Parameters 

LocaleSpecType (int) 

Identifies the type of value in the LocaleSpec argument. 

The constant names of the values of LocaleSpecType are defined in the header unidef.h: 

UNI_TOKEN_POINTER 

LocaleSpec points to a locale token. 

UNI_MBS_STRING_POINTER 

LocaleSpec points to a multibyte character string. 
UNIUCSSTRINGPOINTER 

LocaleSpec points to a UCS character string. 


LocaleSpec (const void *) 

The LocaleSpec argument points to either a character string or a locale token, as indicated by the value 
of the LocaleSpecType argument. 

localeobject (LocaleObject *) 

An address that will receive a pointer to a locale object upon successful completion of 
UniCreateLocaleObj ect. 

Returns 


8 of 154 


Unicode Functions (OS/2 Warp) 


return value (int) - returns 

UniCreateLocaleObject returns one of the following values: 

ULSSUCCESS 

The specified locale is supported and a valid locale object was created. 

ULSUNSUPPORTED 

The specified locale is not supported; the locale object pointer points to undefined data. 

ULS_NOMEMORY 

There is insufficient memory to create the requested locale or the default locale; the locale object 
pointer points to undefined data. 

ULS_IN VALID 

An invalid locale specification string or token was passed; the locale object pointer points to 
undefined data. 


Remarks 

UniCreateLocaleObject creates a locale object for the locale specified by LocaleSpec. The object created is 
an opaque object containing all the data and methods necessary to perform the language-sensitive operations 
or functions that accept an argument of type LocaleObject. If the function is successful, all categories of the 
locale object are created and initialized. 

When the LocaleSpec argument is a pointer to a character string (UCS character string or multibyte character 
string), it identifies the name of the locale to be initialized. The locale name is used to locate physical 
resources associated with this locale. The locale name UNIV is reserved and refers to the definitions that 
provide default behavior for functions. 

When the LocaleSpec argument is a NULL pointer (without regard to the value of the LocaleSpecType 
argument), UniCreateLocaleObject creates a locale object for the UNIV locale. 

When the LocaleSpec argument points to a locale token value as indicated by the value of the 
LocaleSpecType argument, the token identifies the locale to be initialized. 

When the LocaleSpec argument is an empty multibyte or UCS character string, UniCreateLocaleObject 
creates a locale object based upon the settings of the locale environment variables. 


Locale Environment Variables by Precedence and Usage 


Catgeory 

Precedence 

Usage 

LCALL 

Highest 

Setting LC ALL takes precedence over any other locale environment 
variable. 

LCCOLLATE 

Equal 

precedence 

Specifies collation (sorting) rules. 

LCCTYPE 

Equal 

precedence 

Specifies character classification and case conversion. 

LCMESSAGES 

Equal 

precedence 

Specifies the values for affirmative and negative answers, and the language 
for displayed messages. 

LCMONETARY 

Equal 

precedence 

Specifies monetary formats and currency symbol. 
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LCNUMERIC 

Equal 

precedence 

Specifies decimal formats. 

LCTIME 

Equal 

precedence 

Specifies date and time formats. 

LANG 

Lowest 

Setting LANG takes precedence over any undefined locale environment 
variable. This may be used in conjunction with LC COLLATE, 

LC CTYPE, LC MESSAGES, LC MONETARY, LC NUMERIC, and 
LCTIME. 


If the specified locale is valid and supported, UniCreateLocaleObject allocates memory for the new object and 
returns the address of the created locale object in the area pointed to by locale_object. It is the application’s 
responsibility to free this memory with a call to UniFreeLocaleObject when the object is no longer needed. If 
the function fails for any reason, the contents of the area pointed to by locale_object are undefined. 

The locale token provides a shorthand notation for specifying a locale. The fonnat of the locale token is as 
returned by a call to UniLocaleStrToToken. The format is defined as an unsigned integer of four octets. 

Examples of typical usage: 

The locale environment variables are set as follows: 

LANG=de_DE 
LCMONETARY =en_U S 

The LocaleSpec argument is an empty multibyte or UCS character string. 

This example creates a locale object with all categories set to de_DE except for 
LC_MONETARY which has the value of en_US. 

The locale environment variables are set as follows: 

LANG=fr_FR 

The LocaleSpec argument is an empty multibyte or UCS character string. 

This example creates a locale object with all categories set to fr_FR. 

The locale environment variables are set as follows: 

LC_ALL=it_IT 

LANG=fr_FR 

The LocaleSpec argument is an empty multibyte or UCS character string. 

This example creates a locale object with all categories set to it_IT. 

Related Functions 

• UniFreeLocaleObi ect 
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Example 


This example shows how to create a locale object. 

((include <stdio.h> 

((include <unidef.h> 
int main (void) { 

LocaleObject locale_object = NULL; 
int rc = ULS_SUCCESS ; 

/iciciciciciciciciciciciciriririciciciciciciciciciciciciriririricicic-k'k'k'k'k-k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k J 

/* Assumes LANG environment variable set to a valid locale name, */ 
/* such as fr_FR */ 

/*j(*itjtjfjtj<-k-k-k'k'k'k'k-k'k-k'k-k'k'k'k-k-k-k-k-k'k'k-k'k-k-k-k-k'k-k-k'k-k-k-k-k'k'k'k'k-k'k'k-k'k'k'k-k-k-k-k-k'k'k'k'k-k J 

rc = UniCreateLocaleObject (UNI_UCS_STRING_PO INTER, 

(UniChar *)L"", &locale_object) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniCreateLocaleObj ect error: return code = %u\n", rc) ; 
return 1; 

} 

return ULS_SUCCESS; 

} 


UniCreateTransformObject 

UniCreateTransformObject creates a string transform object. 

Format 


((include <unidef.h> 


int UniCreateTransformObject 

(const LocaleObject localeobject, const UniChar *xtype, XformObject *xform_object) 


Parameters 

locale object (const LocaleObject) 

A locale object created by UniCreateLocaleObject or NULL. 


xtype (const UniChar *) 

A UniChar string identifying the transform type. 


xformobject (XformObject *) 

An address that will receive a pointer to an Xform Object upon successful completion of 
UniCreateTransformObject. 

Returns 

return value (int) - returns 
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UniCreateTransformObject returns one of the following: 

ULSSUCCESS 

No errors; the xformobject argument points to a valid transformation object. 

ULSJJNSUPPORTED 

The transformation name type specified by the xtype argument is not supported for localeobject. 


Remarks 

UniCreateTransformObject obtains a transformation object for a transfonnation type as defined in the locale 
indicated by the locale object argument. The function returns a transformation object that can be used as an 
argument in UniTransformStr. 

The following transformation types are defined in all locales: 

lower 

Transfonn to lowercase characters. A character that does not have a lowercase form is returned as itself. 

upper 

Transform to uppercase characters. A character that does not have an uppercase fonn is returned as 
itself. 

compose 

Transform to fully composed form for combined characters. 

decompose 

Transfonn to a string of decomposed characters where multiple characters are used to represent base 
and diacritics. 

hiragana 

Transfonn so that Japanese phonetic characters are in hiragana 

katakana 

Transform so that Japanese phonetic characters are in full size katakana 

kana 

Transform so that Japanese phonetic characters are in half size katakana 

In addition to the above transformation-type names, other transformation-type names in the locale (including 
user-defined transfonnation-type names) may be passed to UniCreateTransformObject through the xtype 
argument. To obtain a successful return, the transformation-type name must be defined in locale object. 

When UniCreateTransformObject completes without errors, the xformobject argument value specifies a 
valid pointer to a transformation object. The transformation object should be used in all subsequent calls to 
UniTransformStr. If the function result is other than ULS SUCCESS, the contents of the area pointed to by 
xform_object are undefined. 

Related Functions 

• UniFreeTransformObject 


Example 


This example shows how to create and use a transform object. 
#include <stdio.h> 

#include <unidef.h> 
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int main (void) { 

LocaleObject locale_object = NULL; 


XformObject 

int 

int 

int 

UniChar 

UniChar 

/* 


xform_object = NULL; 
rc = ULS_SUCCESS ; 
in_unistr_elem = 0; 
out_unistr_elem = 10; 

*pin_unistr = (UniChar *)L"os2"; 
out_unistr [10] ; 

iciciciciciricicicicicicicicicicicicicicicicicic'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k 


*/ 


/* Assumes LANG environment variable set to a valid locale name, */ 
/* such as fr_FR */ 

/•k'k'k-k'k'k'k-k-k-k'k-k'k'k'k'k'k'k'k-k-k-k'k-k-k-k-k-k-k-k-k'k'k'k'k-k-k'k'k'k'k'k'k-k-k-k-k'k-k'k'k-k'k-k-k'k'k-k-k-k-k'k'k'k'k J 


rc = UniCreateLocaleObject (UNI_UCS_STRING_PO INTER, 

(UniChar *)L"", &locale_object) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniCreateLocaleObj ect error: return code = %u\n", rc) ; 
return 1; 


/* Create an upper case transform object */ 
rc = UniCreateTransf ormObject (locale_object, 

(UniChar *)L"upper", &xform_object) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniCreateTransformObject error: return code = %u\n", rc) ; 
return 1; 


/* Calculate the number of elements to transform */ 
in_unistr_elem = UniStrlen (pin_unistr) + 1; 

/* Make call to transform input string to uppercase */ 
rc = UniTransf ormStr (xform_object, pin_unistr, 

&in_unistr_elem, out_unistr, 

&out unistr elem) ; 


if (rc ! = ULS_SUCCESS ) { 

printf ( "UniTransf ormStr error: return code = %u\n", rc) ; 
return 1; 


return ULS SUCCESS; 


} 


UniDeleteUserLocale 


UniDeleteUserLocale is used to delete a locale created by a user. 

Format 


((include <unidef.h> 

int UniDeleteUserLocale 
(UniChar * locale) 


Parameters 

locale (UniChar *) 

A pointer to a UniChar string which defines the name of the locale. 
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Returns 

return value (int) - returns 

UniDeleteUserLocale returns on of the following: 

ULS_SUCCESS 

Successful completion; user locale deleted from disk. 

ULS_NOMATCH 

The requested locale cannot be found. 

ULS_IN VALID 

The locale being deleted is not a user defined locale. 

Remarks 

UniCompleteDeleteLocale is used to remove a previously defined user locale. The locale must have been 
previously created as a user locale. This is accomplished by using the UniCompleteUserLocale API. 

Related Functions 

• UniCompleteUserLocale 

• UniMakeUserLocale 

Example 


This example shows how to delete a user locale once it is no longer 
needed by the user. 

((include <stdio.h> 


((include <unidef.h> 
int main (void) { 

LocaleObject locale_object = NULL; 


/* * Array 
UniChar 
UniChar 
int 


containing user locales */ 

*uniUsrLocales ; 

uniLocaleName [MAX_LOCALE_NAME_LENGTH ] ; 
rc = ULS_SUCCESS ; 

/iciciciciciciciciciciciriciciciciciciciciciciciciciciciricicicicicicic-k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k J 

/* Assumes LANG environment variable set to a valid locale name, */ 
/* such as fr_FR */ 

I'k'k'k-k'k'k-k'k-k-k-k-k'k'k'k-k-k-k-k-k'k-k'k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k'k'k-k-k-k-k-k-k-k-k-k-k-k-k'k'k'k-k-k-k-k-k'k'k-k'k'k J 

rc = UniCreateLocaleObject (UNI_UCS_STRING_POINTER, 

(UniChar *)L"", &locale_object) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniCreateLocaleObj ect error: return code = %u\n", rc) ; 
return 1; 


/* 

Identify the locale to be deleted - making sure the name is in 
Unicode . 

*/ 
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/* Delete a user locale from the disk */ 
rc = UniDeleteUserLocale (uniLocaleName) ; 
if (rc ! = ULS_SUCCESS ) { 

printf ( "UniDeleteUserLocale error: return code = %u\n", rc) ; 
return 1; 

} 

return ULS SUCCESS; 


} 

U niF ree Attr Ob i ect 

UniFreeAttrObject frees the character attribute object. 

Format 


((include <unidef.h> 


int UniFreeAttrObject 

(AttrObject attrobject) 


Parameters 

attr object (AttrObject) 

An attribute object to be freed. The attribute object must have been created by a call to 
UniCreateAttrObj ect. 

Returns 

return value (int) - returns 

UniFreeAttrObject returns one of the following values: 

ULSSUCCESS 

All resources associated with the attribute object specified by the attr object argument have been 
successfully deallocated. 

ULSBADOBJ 

The attribute object specified by attr object is not a valid attribute object. 

Remarks 

UniFreeAttrObject releases all resources associated with the character attribute object allocated by 
UniCreateAttrObj ect. 

The attr object argument specifies a previously allocated attribute object. 

Related Functions 
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• UniQueryAttr 

• UniQueryChar 

• UniQueryCharAttr 

• UniQueryCharType 

Example 


This example shows how to create and free a character attribute object, 
((include <stdio.h> 

((include <unidef.h> 
int main (void) { 

LocaleObject locale_object = NULL; 

AttrObject attr_object = NULL; 
int rc = ULS_SUCCESS ; 

/iciciciriciciciciciciciciciciciciciciciriciciciciciciciricicicicicicic-k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k J 

/* Assumes LANG environment variable set to a valid locale name, */ 
/* such as fr_FR */ 

/•k'k'k-k'k'k'k-k-k-k'k-k'k'k'k'k'k'k'k-k-k-k'k'k-k-k-k-k-k-k-k'k'k'k'k-k-k'k'k'k'k'k'k-k-k-k-k'k-k'k'k-k'k-k-k'k'k-k-k-k-k'k'k'k'k J 

rc = UniCreateLocaleObject (UNI_UCS_STRING_PO INTER, 

(UniChar *)L"", &locale_object) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniCreateLocaleObj ect error: return code = %u\n", rc) ; 
return 1; 

} 

/* Create an alphabetic attribute object */ 
rc = UniCreateAttrObject (locale_object, 

(UniChar *)L"alpha", &attr_object) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniCreateAttrObject error: return code = %u\n", rc) ; 
return 1; 

} 

/* Free the character attribute object */ 
rc = UniFreeAttrObject (attr_object) ; 
if (rc ! = ULS_SUCCESS ) { 

printf ( "UniFreeAttrObj ect error: return code = %u\n", rc) ; 
return 1; 

} 

return ULS_SUCCESS; 

} 


UniF reeLocalelnfo 


UniFreeLocalelnfo frees a locale information structure created by UniQueryLocalelnfo. 

Format 


((include <unidef.h> 

int UniFreeLocalelnfo 

(struct UniLconv *UniLconv_addr) 
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Parameters 

UniLconvaddr (struct UniLconv *) 

A locale information structure created by a call to UniQueryLocalelnfo. 

Returns 

return value (int) - returns 

UniFreeLocalelnfo returns one of the following values: 

ULS_SUCCESS 

The UniLconv structure and associated memory were successfully freed. 

ULSBADOBJ 

The UniLconv addr is not a valid structure. 

Related Functions 

• UniQueryLocalelnfo 

Example 


This example shows how to create and free a locale information structure. 

((include <stdio.h> 

((include <unidef.h> 
int main (void) { 

LocaleObject locale_object = NULL; 

struct UniLconv *puni_lconv = NULL; 

int rc = ULS_SUCCESS ; 

/iciciciciciciciciciciciciriciciciciciciciciciciciciciciricicicicicicic-k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k J 

/* Assumes LANG environment variable set to a valid locale name, */ 

/* such as fr_FR */ 

/-k'k-k-k-k-k-k-k-k-k-k-k-k-k'k'k-k-k'k-k-k'k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k'k'k'k'k-k-k-k-k-k-k-k'k-k-k-k-k-k'k-k'k'k J 

rc = UniCreateLocaleObject (UNI_UCS_STRING_POINTER, 

(UniChar *)L"", &locale_object) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniCreateLocaleObj ect error: return code = %u\n", rc) ; 
return 1; 

} 

/* Retrieve locale information */ 

rc = UniQueryLocalelnfo (locale_object, &puni_lconv) ; 
if (rc ! = ULS_SUCCESS ) { 

printf ( "UniQueryLocalelnfo error: return code = %u\n", rc) ; 
return 1; 

} 

printf ( "Monetary decimal point is %ls\n", puni_lconv->mon_decimal point); 
/* Free the locale information structure */ 
rc = UniFreeLocalelnfo (puni^lconv) ; 
if (rc ! = ULS_SUCCESS ) { 

printf ( "UniFreeLocalelnfo error: return code = %u\n", rc) ; 
return 1; 

} 

return ULS_SUCCESS; 

} 
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UniFreeLocaleObject 

UniFreeLocaleObject frees a locale object that was created by UniCreateLocaleObject. 

Format 


#include <unidef.h> 


int UniFreeLocaleObject 

(LocaleObject localeobject) 


Parameters 

locale object (LocaleObject) 

The Locale Object to be freed, locale object must have been created by a call to 
UniCreateLocaleObject. 

Returns 

return value (int) - returns 

UniQueryLocaleObject returns one of the following values: 

ULS_SUCCESS 

A valid locale specification for the supplied locale object is returned. 
ULSBADOBJ 

Invalid locale object specified. 


Remarks 

The UniFreeLocaleObject function destroys the locale object identified by locale object and frees any 
memory associated with it. 

Related Functions 

• UniQueryLocaleOb j ect 

Example 


This example shows how to create and free a locale object. 

((include <stdio.h> 

((include <unidef.h> 
int main (void) { 

Localeobject locale_object = NULL; 

int rc = ULS_SUCCESS ; 

/* Create a locale object for French in Canada */ 
rc = UniCreateLocaleObject (UNI_UCS_STRING_POINTER, 

(UniChar *)L"fr_CA", &locale_object) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniCreateLocaleObj ect error: return code = %u\n", rc) ; 
return 1; 
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} 

/* Free the locale object that was just created */ 
rc = UniFreeLocaleObject (locale_object) ; 
if (rc ! = ULS_SUCCESS ) { 

printf ( "UniFreeLocaleObject error: return code = %u\n", rc) ; 
return 1; 

} 

return ULS SUCCESS; 


} 


UniFreeMem 


UniFreeMem frees memory allocated by UniQueryLocaleObject. 

Format 


#include <unidef.h> 


int UniFreeMem 

(void *memory) 


Parameters 

memory (void *) - in/out 

A pointer to the memory to be freed. 

Returns 

Returns (int) - returns 

UniFreeMem returns one of the following values: 
ULSSUCCESS 

Indicates success. 

ULSBADOBJ 

Invalid pointer in memory. 


Remarks 

UniFreeMem frees memory allocated by ULS functions. For example, the memory allocated for the 
localename parameter of UniQueryLocaleObject should be freed using UniFreeMem. 

Example 


This example shows how to free memory allocated by a ULS function, 
((include <stdio.h> 

((include <unidef.h> 
int main (void) { 

LocaleObject locale_object = NULL; 

int rc = ULS SUCCESS; 
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char *locale_name; 

/* Create a locale object for French in Canada */ 
rc = UniCreateLocaleObject (UNI_UCS_STRING_PO INTER, 

(UniChar *)L"fr_CA", &locale_object) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniCreateLocaleObj ect error: return code = %u\n", rc) ; 
return 1; 

} 

/* Determine the locale name for the LC_MESSAGES category */ 
rc = UniQueryLocaleObject (locale_object, LC_MESSAGES, 

UN I_MBS_STRING_PO INTER, 

(void **) &locale_name) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ("UniQueryLocaleObject error: return code = %u\n", rc) ; 
return 1; 

} 

/* Free the memory allocated by UniQueryLocaleObject */ 
rc = UniFreeMem ( (void ** ) locale_name ) ; 
if (rc ! = ULS_SUCCESS ) { 

printf ("UniFreeMemObject error: return code = %u\n", rc) ; 
return 1; 

} 

return ULS_SUCCESS; 

} 


UniFreeTransformObiect 

UniFreeTransformObject frees a string transformation object. 

Format 


((include <unidef.h> 


int UniFreeTransformObject 

(XformObject xformobject) 


Parameters 

xform object (XformObject) 

The transfonn object to be freed. The transform object must have been created by a call to 
UniCreateTransformObject. 

Returns 

return value (int) - returns 

UniFreeTransformObject returns one of the following: 

ULSSUCCESS 

Specifies that all resources associated with the transfonnation object specified by the xform object 
argument have been successfully deallocated. 
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Remarks 

UniFreeTransformObject releases all resources associated with a transformation object previously obtained by 
UniCreateTransformObj ect. 

Related Functions 

• UniCreateTransformObject 

Example 


This example shows how to create and free a transform object. 

((include <stdio.h> 

((include <unidef.h> 
int main (void) { 

LocaleObject locale_object = NULL; 

XformObject xform_object = NULL; 
int rc = ULS_SUCCESS ; 

/-k'k'k-k'k-k-k-k-k-k-k'k-k-k'k-k-k'k'k-k-k-k-k'k-k-k-k-k-k-k-k'k'k'k'k-k-k-k-k'k'k-k-k-k'k'k-k'k'k'k-k-k-k-k-k'k-k-k-k-k'k-k'k'k'k j 

/* Assumes LANG environment variable set to a valid locale name, */ 
/* such as fr_FR */ 

/iciciciciciciciciciciciciciririciciciciciciciciciciciciriririricicicic-k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k J 

rc = UniCreateLocaleObject (UNI_UCS_STRING_PO INTER, 

(UniChar *)L"", &locale_object) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniCreateLocaleObj ect error: return code = %u\n", rc) ; 
return 1; 

} 

/* Create an upper case transform object */ 
rc = UniCreateTransformObject (locale_object, 

(UniChar *)L"lower", &xform_object) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ("UniCreateTransformObject error: return code = %u\n", rc) ; 
return 1; 

} 

/* Free the transform object created by UniCreateTransformObject */ 
rc = UniFreeTransformObject (xform_object) ; 
if (rc ! = ULS_SUCCESS ) { 

printf ("UniFreeTransformObject error: return code = %u\n", rc) ; 
return 1; 

} 

return ULS_SUCCESS; 

} 


UniLocaleStr To Token 


UniLocaleStrToToken converts a locale specification string to a token. 

Format 
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((include <unidef.h> 

int UniLocaleStrToToken 

(int LocaleStringType, const void *locale_string, LocaleToken *locale_token) 


Parameters 

LocaleStringType (int) 

Informs UniLocaleStrToToken of the type of string being passed in the locale string variable. 

The LocaleStringType argument can take any of the following values, which are constants defined in 
the header unidef.h: 

UNIMB SSTRIN GPOINTER 

Requests that a multibyte string pointer is held in locale string. 
UNIUCSSTRINGPOINTER 

Requests that a UCS string pointer is held in locale string. 


locale string (const void *) 

The locale specification string. 

localetoken (LocaleToken *) 

An address that will receive a pointer to the newly created token corresponding to locale string. 

Returns 

return value (int) - returns 

UniLocaleStrToToken returns one of the following values: 

ULS_SUCCESS 

A valid locale token for the supplied locale object is returned. 

ULSOTHER 

The C locale is because LOCALE.DLL cound not be found. 

ULSUNSUPPORTED 

The locale name is valid but the locale cound not be found. 


Remarks 

UniLocaleStrToToken accepts, as an argument, a locale string qualified by the value of the LocaleStringType 
argument. It returns a locale token pointed to by locale_token if such a token exists for that locale string. 
UniLocaleStrToToken allocates memory to hold the locale token value. If no locale token exists for the 
supplied locale string, the value returned in locale_token is undefined. 

Related Functions 

• UniLocaleTokenToStr 

Example 
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This example shows how to convert a locale specification string to a token, 
((include <stdio.h> 

((include <unidef.h> 
int main (void) { 

UniChar *locale_string = L"de_DE"; /*German in Germany locale string */ 

LocaleToken locale_token; 

int rc = ULS_SUCCESS ; 

rc = UniLocaleStrToToken (UNI_UCS_STRING_POINTER, 

(void * ) locale_string, 

&locale_token) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniLocaleStrToToken error: return code = %u\n", rc) ; 
return 1; 

} 

return ULS_SUCCESS; 

} 


UniLocaleTokenToStr 


UniLocaleTokenToStr converts a locale token to a locale specification string. 

Format 


((include <unidef.h> 

int UniLocaleTokenToStr 

(const LocaleToken localetoken, int LocaleStringType, void **locale_string) 


Parameters 

locale token (const LocaleToken) 

A token identifying a locale. 

LocaleStringType (int) 

The LocaleStringType argument can take any of the following values, which are constants defined in 
the header unidef.h: 

UNIMBSSTRINGPOINTER 

Requests that a multibyte string pointer be returned. 

UNIU C SSTRIN GPOINTER 

Requests that a UCS string pointer be returned. 


locale string (void **) 

An address of a pointer variable locale string that will contain the locale specification string corresponding to 
locale token. 
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Returns 

return value (int) - returns 

The UniLocaleTokenToStr function returns one of the following values: 
ULS_SUCCESS 

A valid locale specification for the supplied locale object is returned. 
ULS_IN VALID 

The locale token supplied could not be matched to a locale string. 

ULSJVOMEMORY 

There is insufficient memory to store the locale string. 


Remarks 

The UniLocaleTokenToStr() function accepts as an argument a locale token in locale_token and returns a 
pointer to a locale string in locale_string qualified by the LocaleStringType argument. The 
UniLocaleTokenToStr() function allocates memory to hold the locale string value. It is the application's 
responsibility to free the memory using UniFreeMem() when the locale string value is no longer needed. If no 
locale string can be generated for the supplied locale token, the value returned in Iocale_string is undefined. 

Related Functions 

• UniLocaleStrToToken 

Example 


This example shows how to convert a locale token to a locale specification string. 
#include <stdio.h> 


#include <unidef.h> 
int main (void) { 

UniChar *locale_stringl = L"de_DE"; /*German in Germany locale string */ 

UniChar *locale_string2 ; 

LocaleToken locale token; 


int 


rc = ULS_SUCCESS ; 

rc = UniLocaleStrToToken (UNI_UCS_STRING_POINTER, 

(void * ) locale_stringl , 

&locale_token) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniLocaleStrToToken error: return code = %u\n", rc) ; 
return 1; 


/* Convert the token to a locale string */ 

rc = UniLocaleTokenToStr (locale_token, 

UNI_UCS_STRING_PO INTER, 

(void ** ) &locale_string2 ) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniLocaleTokenToStr error: return code = %u\n", rc) ; 
return 1; 

} 

return ULS SUCCESS; 
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} 

UniMakeUserLocale 

UniMakeUserLocale creates a user locale from a base system locale. 

Format 


#include <unidef.h> 

int UniMakeUserLocale 

(UniChar * newName, UniChar * baseName) 


Parameters 

newName (UniChar * ) 

The name of the new locale. 

baseName (UniChar * ) 

The name of the locale to base the new locale after. 

Returns 

return value (int) - returns 

UniMakeUserLocale returns one of the following values: 

ULSSUCCESS 

The user locale has been created. 

ULS_NOMATCH 

The base system locale does not exist. 

ULSINVALID 

The name supplied contains an illegal character, is too long or redefines a base system locale. 

ULS_NOOP 

The name supplied currently exists as a locale name. 

ULS_NOMEMORY 

Cannot allocate memory for the new locale. 

Remarks 

The names for the new locale and the base system locale must be ASCII-7 chars and at most eight characters, 
in length. An existing locale name must be given as the base locale name. 

If the user locale already exists, a ULS NOOP return code will be given, therefore, this API can always be 
called before making an update to ensure that the user locale exists. 

Related Functions 

• UniCompleteUserLocale 
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• UniDeleteUserLocale 

Example 


This example shows how to make a user locale. 
#include <stdio.h> 


((include <unidef.h> 
int main (void) { 

LocaleObject locale_obj ect = NULL; 


int rc = ULS_SUCCESS ; 

UniChar *plocaleName; 

UniChar *puniSysLocale ; 

/* Create current default locale object for this process */ 
rc = UniCreateLocaleObject (UNI_UCS_STRING_POINTER, 

(UniChar *)L"", 

&locale_object) ; 

if (rc) { 

printf ( "UniCreateLocaleObject error: return code = %u\n", rc) ; 
return 1; 


/* Query the name of the default locale object */ 
rc = UniQueryLocaleObject (locale_object, 

LC_ALL , 

UNI_UCS_STRING_PO INTER, 
(void**) SplocaleName ) ; 


if (rc) { 

printf ( "UniQueryLocaleObject error: return code = %u\n", 
return 1; 


rc) ; 


/* Get the locale name from the locale object string */ 
puniSysLocale = UniStrtok (plocaleName , (UniChar *)L" "); 

/* Make a new locale */ 

rc = UniMakeUserLocale (puniSysLocale, puniSysLocale); 
if (rc) { 

printf ( "UniMakeUserLocale error: return code = %u\n", rc) ; 
return 1; 

} 

/* free the space used by the locale object string */ 
UniFreeMem (plocaleName) ; 
if (locale_object) 

UniFreeLocaleObject (locale_object) ; 
return ULS SUCCESS; 


} 


UniMapCtryToLocale 

UniMapCtryToLocale converts an unsigned long country code into a locale name represented as a UniChar 
string that is acceptable as input to other Unicode APIs. 

Format 


((include <unidef.h> 
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int UniMapCtryToLocale 

(unsigned long ulCountryCode, UniChar *ucsLocaleName, sizet n) 


Parameters 

ulCountryCode (unsigned long) - input 
An OS/2 country code. 

ucsLocaleName (UniChar *) - output 

A buffer for placing the Unicode string. 

n (size t) - input 

Size, in characters, of the ucsLocaleName buffer. This should be at least 8 Unicode characters. 

Returns 

return value (int) - returns 
Error code. 

UniMapCtryToLocale returns one of the following values: 

ULSSUCCESS 

A valid locale name for the supplied country code is returned. 

UL SBUFFERFULL 

The buffer is not large enough to hold the locale name. 

ULSINVALID 

An invalid country code or buffer was specified. 

Related Functions 

• UniMapCpToUcsCp 

Example 


This example shows how to map a country code to a locale name. 

((include <stdio.h> 

((include <unidef.h> 
int main (void) { 

UniChar ucs_locale_name [ 8 ] ; 

size_t num_elems = 8; 

unsigned long countrynum = 1; 

LocaleObject localeobject = NULL; 
int re = ULS SUCCESS; 

/iciciciciciciciciciciciciciciciciciciciciciciciciciciciricicicicicicic-k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k J 

/* Convert country number to a locale name */ 

I ★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★■A' j 

rc = UniMapCtryToLocale (country_num, ucs_locale_name , num_elems); 
if (rc ! = ULS SUCCESS) { 
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printf ( "UniMapCtryToLocale error: return code = %u\n", rc) ; 
return 1; 

} 

rc = UniCreateLocaleObject (UNI_UCS_STRING_PO INTER, 

ucs_locale_name, &locale_object) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniCreateLocaleObj ect error: return code = %u\n", rc) ; 
return 1; 

} 

return ULS SUCCESS; 


} 


UniQueryAlnum 

UniQueryAlnum queries character attributes. 

Format 


((include <unidef.h> 


int UniQueryAlnum 

(const LocaleObject localeobject, UniChar uc) 


Parameters 

locale object (const LocaleObject) 

A locale object created by UniCreateLocaleObject or NULL. 

uc (UniChar) 

The UniChar character to query. 

Returns 

return value (int) - returns 

If the result of the test is true, the function returns 1 . Otherwise, 0 is returned. 

Remarks 

This function provides the functionality of UniCreateAttrObject, UniQueryCharAttr, and UniFreeAttrObject 
as an atomic operation for the invariant attributes. 

The locale may be specified as NULL to indicate default Unicode character attributes 

Related Functions 

• UniQueryAttr 

• UniQueryChar 

• UniQueryCharAttr 

• UniQueryCharType 
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Example 


This example shows how to query character attributes. 

((include <stdio.h> 

((include <unidef.h> 
int main (void) { 

LocaleObject locale_object = NULL; 

int result = 0; 

int rc = ULS_SUCCESS ; 

UniChar uni_char = L'a'; /* Unicode lowercase Latin letter a */ 

/iciciciciciciciciciciciciciciriciciciciciciciciciciciciciciciricic-k'k'k'k'k'k-k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k-k'k'k'k'k'k'k J 

/* Assumes LANG environment variable set to a valid locale name, */ 
/* such as fr_FR */ 

/i<j(*itjtjtjfj<j(j<j<'k'k-k'k-k-k-k-k-k-k-k'k-k-k-k-k-k'k'k'k-k-k-k-k-k-k'k'k'k-k-k-k-k'k'k'k'k-k-k-k-k'k'k'k-k-k-k-k-k'k'k'k'k-k j 

rc = UniCreateLocaleObject (UNI_UCS_STRING_PO INTER, 

(UniChar *)L"", &locale_object) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniCreateLocaleObj ect error: return code = %u\n", rc) ; 
return 1; 

} 

/* Query character attribute */ 

result = UniQueryAlnum (locale_object, uni_char) ; 
if (result) 

printf ( "UniChar character %04X is alphanumeric\n" , uni^char) ; 
else 

printf ( "UniChar character %04X is not alphanumericXn" , uni_char) ; 

return ULS_SUCCESS; 

} 


UniQuery Alpha 

UniQueryAlpha queries character attributes. 

Format 


((include <unidef.h> 


int UniQueryAlpha 

(const LocaleObject locale object, UniChar uc) 


Parameters 

locale object (const LocaleObject) 

A locale object created by UniCreateLocaleObject or NULL. 

uc (UniChar) 

The UniChar character to query. 

Returns 
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Return Value (int) - returns 

If the result of the test is true, the function returns 1 . Otherwise, 0 is returned. 

Remarks 

This function provides the functionality of UniCreateAttrObject, UniQueryCharAttr, and UniFreeAttrObject 
as an atomic operation for the invariant attributes. 

The locale may be specified as NULL to indicate default Unicode character attributes 

Related Functions 

• UniQueryAttr 

• UniQueryChar 

• UniQueryCharAttr 

• UniQueryCharType 

Example 


This example shows how to query character attributes. 

((include <stdio.h> 

((include <unidef.h> 

int main (void) { 

int result = 0; 

int rc = ULS_SUCCESS ; 

UniChar uni_char = L'a'; /* Unicode lowercase Latin letter a */ 

/* Query character attribute */ 
result = UniQueryAlpha (NULL, uni char); 
if (result) 

printf ( "UniChar character %04X is alphabetic\n" , uni_char) ; 
else 

printf ( "UniChar character %04X is not alphabetic\n" , uni_char) ; 

return ULS_SUCCESS; 

} 


UniQueryAttr 

UniQueryAttr returns the value associated with attribute name supplied by the user. 

Format 


((include <unidef.h> 


ulong UniQueryAttr 

(UniChar * attrName) 


Parameters 
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attrName (UniChar *) 

The name of a character attribute. 

Returns 

Return Value (ulong) - returns 

If the attribute name is known, the function returns the attribute value. Otherwise, 0 is returned. 

Remarks 

This function provides the numeric value for the standard attributes such as alpha, graph, and number. In 
addition, this function provides the numeric value for other attributes such as Hiragana, diacritic, halfwidth 
etc. The table below contains the valid attribute names. Valid names are all in lower case. 

Attribute names that begin with a lower case letter may be ORed together. 

Attribute Name and Description Table 


Attr Name 

Attribute Define 

Description of Attribute 

alnum 

CT_ALNUM 

Alphabetic and numeric characters 

alpha 

CTALPHA 

Letters and linguistic marks 

ascii 

CTASCII 

Standard ASCII character 

blank 

CT_BLANK 

Space and Tab 

cntrl 

CTCNTRL 

Control and format characters 

diacritic 

C3DIACRITIC 

Diacritic 

digit 

CTDIGIT 

Digits 0 through 9 

fullwidth 

C3FULLWIDTH 

Full width variant 

graph 

CTGRAPH 

All except controls and space 

halfwidth 

C3HALFWIDTH 

Half width variant 

hiragana 

C3HIRAGANA 

Hiragana character 

ideograph 

C3 IDEOGRAPH 

Kanj i/Han character 

kashida 

C3KASHIDA 

Arabic tatweel (used to stretch characters) 

katakana 

C3KATAKANA 

Katakana character 

lower 

CTLOWER 

Lower case alphabetic character 
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nonspacing 

C3NONSPACING 

Non-spacing mark 

nsdiacritic 

C3NSDIACRITIC 

Non-spacing diacritic 

nsvowel 

C3_NS VOWEL 

Non-spacing vowel 

number 

CT_NUMBER 

Integers between 0 and 9 

print 

CTPRINT 

Everything except control characters 

punct 

CTPUNCT 

Punctuation marks 

space 

CTSPACE 

Whitespace and line ends 

symbol 

CTSYMBOL 

Symbol 

upper 

CTUPPER 

Upper case alphabetic character 

vowelmark 

C3_V OWELMARK 

Vowel mark 

xdigit 

CTXDIGIT 

Hexadecimal digits (0-9, a-f or A-F) 

a pi 

CHSAPL 

APL character 

arabic 

CHSARABIC 

Arabic character 

arrow 

CHSARROW 

Arrow character 

bengali 

CHSBENGALI 

Bengali character 

bopomofo 

CHSBOPOMOFO 

Bopomofo character 

box 

CHSBOX 

Box or line drawing character 

currency 

CHSCURRENCY 

Currency Symbol 

cyrillic 

CHSCYRILLIC 

Cyrillic character 

dash 

CHSDASH 

Dash character 

dingbat 

CHSDINGBAT 

Dingbat 

fraction 

CHSFRACTION 

Fraction value 

_greek 

CHSGREEK 

Greek character 

gujarati 

CHSGUJARATI 

Gujarati character 

gurmukhi 

CHSGURMUKHI 

Gurmukhi character 
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hanguel 

CHSHANGUEL 

Hanguel character 

_hebrew 

CHSHEBREW 

Hebrew character 

hiragana 

CHSHIRAGANA 

Hiragana character set 

katakana 

CHS_KATAKANA 

Katakana character set 

lao 

CHSLAO 

Laotian character 

latin 

CHSLATIN 

Latin character 

_linesep 

CHS_LINESEP 

Line separator 

math 

CHSMATH 

Math symbol 

_punctstart 

CHSPUNCTSTART 

Punctuation start 

_punctend 

CHSPUNCTEND 

Punctuation end 

tamil 

CHSTAMIL 

Tamil character 

_telegu 

CHSTELEGU 

Telegu character 

thai 

CHSTHAI 

Thai character 

_userdef 

CHSUSERDEF 

User defined character 

#arabicnum 

C2AR AB ICNUMB ER 

Arabic numbers 

#blocksep 

C2BLOCKSEPARATOR 

Block separator 

#commonsep 

C2COMMONSEPARATOR 

Common separator 

#euronum 

C2_EUROPENUMBER 

European number 

#eurosep 

C2EUROPESEPARATOR 

European separator 

#euroterm 

C2EUROPETERMINATOR 

European terminator 

#left 

C2LEF TT ORIGHT 

Left to right text orientation 

#mirrored 

C2MIRRORED 

Symmetrical text orientation 

#neutral 

C20THERNEUTRAL 

Other neutral 

#right 

CTRIGHTTOLEFT 

Right to left text orientation 

#whitespace 

C2WHITESPACE 

Whitespace 
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Related Functions 

• UniQueryChar 

• UniQueryCharAttr 

• UniOueryCharType 

Example 


This example shows how to query character attribute values using the 
character attributes. 

((include <stdio.h> 

((include <unidef.h> 
int main (void) { 

char name [ 33 ] ; 

UniChar uname [33]; 

UniChar * up; 
char * cp; 
ulong rc; 

/* 

* Ask the user for an attribute name 
*/ 

printf ( "Enter attribute name:"); 
scanf ("%s", Sname) ; 
if (strlen (name) > 32) 
return 1; 

/* 

* Convert name to Unicode 
*/ 

cp = name ; 
up = uname; 
while (*cp) { 

*up++ = (UniChar) (*cp++) ; 

} 

* up = 0 ; 

/* 

* Query the attribute and print the value 
*/ 

rc = UniQueryAttr (tolower (uname) ) ; 
if (rc == 0) { 

printf ( "UniQueryAttr error: return code = %u\n", rc) ; 
return 1; 

} else 

printf ("%s attribute = %x\n", name, rc) ; 
return ULS_SUCCESS; 

} 


UniQueryBlank 

UniQueryBlank queries character attributes. 

Format 


((include <unidef.h> 
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int UniQueryBlank 

(const LocaleObject localeobject, UniChar uc) 


Parameters 

locale object (const LocaleObject) 

A locale object created by UniCreateLocaleObject or NULL. 

uc (UniChar) 

The UniChar character to query. 

Returns 

Return Value (int) - returns 

If the result of the test is true, the function returns 1 . Otherwise, 0 is returned. 

Remarks 

This function provides the functionality of UniCreateAttrObject, UniQueryCharAttr, and UniFreeAttrObject 
as an atomic operation for the invariant attributes. 

The locale may be specified as NULL to indicate default Unicode character attributes 

Related Functions 

• UniQueryAttr 

• UniQueryChar 

• UniQueryCharAttr 

• UniQueryCharType 

Example 


This example shows how to query character attributes. 

((include <stdio.h> 

((include <unidef.h> 
int main (void) { 

Localeobject locale_object = NULL; 

int result = 0; 

int rc = ULS_SUCCESS ; 

UniChar uni^char = L' /* Unicode space character */ 

/-k'k'k-k-k-k-k-k-k-k-k-k'k'k'k-k-k-k-k-k'k-k-k-k-k-k-k-k'k'k'k-k-k-k-k-k-k-k-k-k-k-k-k-k-k'k-k'k-k-k-k-k-k-k-k-k-k-k-k-k'k'k'k-k-k j 

/* Assumes LANG environment variable set to a valid locale name, */ 
/* such as fr_FR */ 

liciciciciciciciciciciciciciciciciciciciciciciciciciciciricicicicicicic-k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k J 

rc = UniCreateLocaleObject (UNI_UCS_STRING_POINTER, 

(UniChar *)L"", &locale_object) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniCreateLocaleObj ect error: return code = %u\n", rc) ; 
return 1; 

} 

/* Query character attribute */ 

result = UniQueryBlank (locale object, uni char); 
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if (result) 

printf ( "UniChar character %04X is a blank characterin'', uni char); 
else 

printf ( "UniChar character %04X is not a blank characterin'', uni char); 

return ULS_SUCCESS; 

} 


UniQueryChar 

UniQueryChar determines if the character supplied has the attribute(s) requested. 

Format 


((include <unidef.h> 


int UniQueryChar 

(UniChar uc, ULONG attrName) 


Parameters 

uc (UniChar) 

The Unicode character whose attribute(s) are being examined. 
attrName (ULONG) 

The name of the attribute being examined in the Unicode character. 

Returns 

Return Value (ulong) - returns 

If the named attribute is true for the Unicode character supplied, the function returns a 1 . Otherwise, 0 
is returned. 

Remarks 

This function takes the attributes supplied by the caller and tests the character to determine if they are true for 
that Unicode character. Attribute names that have a leading _ or # character represent classes of characters. 
These attributes must be tested as individual attributes. The remaining attributes can be or'ed together before 
testing. 

Related Functions 

• UniQueryAttr 

• UniQueryCharAttr 

• UniQueryCharType 

Example 
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This example shows how to query if a character has particular attributes, 
((include <stdio.h> 

((include <unidef.h> 
int main (void) { 

int result = 0; 

UniChar uni_char = L'A'; /* Unicode A character */ 

/* Query character for upper case and graphic attributes */ 
result = UniQueryChar (uni_char , C1_UPPER | | C1_GRAPH) ; 
if (result) 

printf ( "UniChar is upper case and a graphic characterin'') ; 
else 

printf ( "UniChar is not upper case and a graphic character\n"_; 
/* Query character for Latin character set attribute */ 
result = UniQueryChar (uni_char, CHS_LATIN) ; 
if (result) 

printf ( "UniChar is a Latin characterin'') ; 
else 

printf ( "UniChar is not a Latin characterin'') ; 
return ULS_SUCCESS; 

} 


UniQueryChar Attr 

UniQueryCharAttr queries the attributes of a character. 

Format 


((include <unidef.h> 


int UniQueryCharAttr 

(AttrObject attrobject, UniChar uc) 


Parameters 

attr object (AttrObject) 

An attribute object created by UniCreateAttrObject. 
uc (UniChar) 

The UniChar character whose attributes will be queried. 

Returns 

return value (int) - returns 

If the result of the test is true (the code element has the attribute associated with the attribute object, 
attr object), UniQueryCharAttr returns the value 1. 

If the result of the test is false, UniQueryCharAttr returns the value 0. 

Remarks 

UniQueryCharAttr determines whether the code element uc has the attributes specified by the attribute object 
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argument, attrobject. 

Related Functions 

• UniQueryAttr 

• UniQueryChar 

• UniQueryCharType 

Example 


This example shows how to create and use a character attribute object, 
((include <stdio.h> 


((include <unidef.h> 
int main (void) { 

LocaleObject locale_object = NULL; 


AttrObject attr_object = NULL; 
int result = 0; 


int rc = ULS_SUCCESS ; 

UniChar uni char = L'c'; /* Unicode lowercase Latin letter c */ 

/-k-k'k-k-k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-k'k-k-k-k-k-k-k-k'k'k-k'k-k'k-k-k-k-k-k-k-k-k-k-k'k'k'k'k'k-k-k-k-k-k-k'k-k-k-k-k'k'k'k'k 

/* Assumes LANG environment variable set to a valid locale name, 
/* such as fr_FR 

/iciciciciciciciciciciciciciriciciciciciciciciciciciciciricicicicic-k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k 


*/ 

*/ 

*/ 

*/ 


rc = UniCreateLocaleObject (UNI_UCS_STRING_PO INTER, 

(UniChar *)L"", &locale_object) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniCreateLocaleObj ect error: return code = %u\n", rc) ; 
return 1; 


/* Create an attribute object */ 

rc = UniCreateAttrObject (locale_object, 

(UniChar *)L"alpha xdigit", &attr_object) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniCreateAttrObject error: return code = %u\n", rc) ; 
return 1; 


/* Make call to determine if character matches attributes */ 
result = UniQueryCharAttr (attr_object, uni_char) ; 
if (result) 

printf ( "UniChar character %04X matches attributes\n" , uni_char) ; 
else 

printf ( "UniChar character %04X does not match attributes\n" , uni_char) ; 
return ULS SUCCESS; 


} 


UniQueryCharType 

UniQueryCharType is used to query the type of the character. 

Format 


((include <unidef.h> 
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UNICTYPE * UniQueryCharType 
( UniChar uc ) 


Parameters 

uc (UniChar) 

The UniChar character whose type will be queried. 

Returns 

return value (UNICTYPE *) - returns 

A pointer to a structure of type UNICTYPE Iis returned from this call. 

Remarks 

UniQueryCharType is designed to provide information to support both the XPG/4 character type as well as 
the Win32 GetCharType type. Where the function is similar, this API is designed to be a superset of the 
Win32 function so that the Win32 functions can be supported by masking off bits in the returned data 
structure. GetCharType is similar to the C library "is" functions. 

The UNICTYPE structure contains character set infonnation, infonnation regarding Bidirectional attributes, 
information regarding XPG/4 attributes and information on extended attributes. 

Related Functions 

• UniQueryAttr 

• UniQueryChar 

• UniQueryCharAttr 

• UniQueryCharTypeTable 

Example 


This example shows how to query a character type. 

((include <stdio.h> 

((include <unidef.h> 
int main (void) { 

UNICTYPE * uct; 

UniChar uni char = 0x3456; /* Some random Unicode character */ 

/* Query the character type */ 
uct = UniQueryCharType (uni_char) ; 

/* Examine the returned structure to determine information about 
the character. For example, what is its BiDi orientation and 
is the character Arabic or Hebrew? */ 
if (uct->bidi==C2_RIGHTTOLEFT) 

printf ( "Character is presented right to left\n"); 
else 

printf ( "Character is presented left to right\n"); 

if (uct->charset==CHS_ARABIC) 

printf ( "Character is ArabicXn"); 
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else if (uct->charset==CHS_HEBREW) 
printf ( "Character is Hebrew\n"); 
else 

printf ( "Character is not Arabic or Hebrew\n"); 

return ULS_SUCCESS; 

} 


UniQueryCharTypeTable 

UniQueryCharTypeTable is used to query the type of the character. 

Format 


((include <unidef.h> 


ULONG UniQueryCharTypeTable 

( ULONG * count, UNICTYPE * * unictype ) 


Parameters 

count (ULONG *) 

count is set to the length of the table being accessed, 
unictype (UNICTYPE * *) 

unictype is set to point to a table of UNICTYPE structures. 

Returns 

return value (ULONG) - returns 

A ULONG equal to zero is always returned. 

Remarks 

UniQueryCharTypeTable is passed a pointer to a count and a pointer to a table of UNICTYPE structures, 
count is set to the number of entries in the UNICTYPE structure table, unictype is set to the first structure in 
the table. 

Related Functions 

• UniQueryAttr 

• UniQueryChar 

• UniQueryCharAttr 

• UniQueryCharType 

Example 


This example shows how to query a character type table, 
((include <unidef.h> 
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(finclude <stdlib.h> 

/* 

* StringBidi: Determine bidi types for each character in a string 

* Return string of bidi bits, and return value with 

* OR of all bits . 

*/ 

USHORT StringBidi (UniChar * instr, USHORT * charsets) { 

ULONG count; 

UNICTYPE * typetab; 

USHORT index, *pcs, out; 
int rc, i, len; 

/* 

* Get addressability to the character type table 
*/ 

UniQueryCharTypeTable (Scount, Stypetab) ; 

/* 

* Create an output string 
*/ 

len = UniStrlen (instr ) ; 

UniQueryStringType (instr, len, charsets, CT_INDEX) ; 

/* 

* Replace each index with bidi flags 
*/ 

pcs = charsets; 
out = 0 ; 

for (i=0; i<len; i++) { 

index = *pcs; 

*pcs = 0; 

if (typetab [index] .bidi == C2 RIGHTTOLEFT) 

*pcs |= 1; 

if (typetab [index] . charset == CHS_ARABIC) 

*pcs |= 2; 

if (typetab [ index ]. charset == CHS_HEBREW) 

*pcs |= 4; 
out |= *pcs++; 

} 

return out; 


UniQueryCntrl 

UniQueryCntrl queries character attributes. 

Format 


#include <unidef.h> 


int UniQueryCntrl 

(const LocaleObject locale object, UniChar uc) 


Parameters 
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localeobject (const LocaleObject) 

A locale object created by UniCreateLocaleObject or NULL. 

uc (UniChar) 

The UniChar character to query. 

Returns 

Return Value (int) - returns 

If the result of the test is true, the function returns 1 . Otherwise, 0 is returned. 

Remarks 

This function provides the functionality of UniCreateAttrObject, UniQueryCharAttr, and UniFreeAttrObject 
as an atomic operation for the invariant attributes. 

The locale may be specified as NULL to indicate default Unicode character attributes 

Related Functions 

• UniQueryAttr 

• UniQueryChar 

• UniQueryCharAttr 

• UniQueryCharTyp e 

• UniQueryCharTypeTable 

Related Functions 
Example 


This example shows how to query character attributes. 

((include <stdio.h> 

((include <unidef.h> 
int main (void) { 

Localeobject locale_object = NULL; 

int result = 0; 

int rc = ULS_SUCCESS ; 

UniChar uni char = OxOOOA; /* Unicode newline character */ 

/-k'k'k-k-k-k-k-k-k'k-k'k'k'k'k-k-k-k-k'k-k-k'k'k-k-k-k-k-k-k-k'k'k'k'k-k-k-k-k'k-k-k-k-k'k'k-k'k'k'k'k-k-k-k-k'k-k'k'k-k-k-k-k'k-k J 

/* Assumes LANG environment variable set to a valid locale name, */ 

/* such as fr_FR */ 

/iciciciciciciciciciciciciciriciciciciciciciciciciciciciririciricicicic-k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k J 

rc = UniCreateLocaleObject (UNI_UCS_STRING_POINTER, 

(UniChar *)L"", &locale_object) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniCreateLocaleObj ect error: return code = %u\n", rc) ; 
return 1; 

} 

/* Query character attribute */ 

result = UniQueryCntrl (locale_object, uni_char) ; 
if (result) 

printf ( "UniChar character %04X is a control characterin'', uni_char) ; 
else 

printf ( "UniChar character %04X is not a control characterin'', uni_char) ; 
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return ULS_SUCCESS; 

} 


UmQuervCoimtryName 

UniQueryCountryName returns the name of the country in the language specified. 

Format 


((include <unidef.h> 


int UniQueryCountryName 

(UniChar * country, UniChar * isolang, UniChar * * infoitem) 


Parameters 

country (UniChar *) 

The two character ID of the country to query, 
isolang (UniChar *) 

The two character ID of the language used to return the country name. 

infoitem (UniChar * *) 

A pointer to the country name. 

Returns 

Return Value (int) - returns 

UniQueryCountryName returns one of the following values: 

ULSIN VALID 

The country ID supplied is not known. 

0 is returned upon success and the country name has been returned to the caller. 

Remarks 

This function only queries system provided locales to determine valid country names. 

Related Functions 

• UniQueryLanguageName 

Example 


This example shows how to query a country name, 
((include <stdio.h> 
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((include <unidef.h> 
((include <ulsitem.h> 


int main (void) { 

LocaleObject locale_object = NULL; 
int 
int 

UniChar 
UniChar 
UniChar 
UniChar 
UniChar 


result = 0; 

rc = ULS_SUCCESS ; 

*pinf o; 

*langName; 
*countryName ; 
*mriLanguage ; 
uni char = L ' 5 ' ; 


/* Unicode number 5 


character */ 


J iciciriciciciciciciciciciciciciciciciciriciciciciciciciciciciciciricir'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k j 

/ * Assumes LANG environment variable set to a valid locale name, */ 
/* such as fr_FR */ 

j ititit'k'k'k-k-k-k-k-k-k-k-k-k-k'k'k'k'k-k'k'k'k-k-k-k-k-k-k-k-k'k'k'k'k-k-k-k-k-k-k-k-k-k-k-k-k'k'k'k'k'k'k'k'k-k-k-k-k'k-k-k-k-k j 

rc = UniCreateLocaleObject (UNI_UCS_STRING_POINTER, 

(UniChar *)L"", &locale_object) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniCreateLocaleObj ect error: return code = %u\n", rc) ; 
return 1; 

} 


/* Determine the language to get the country name in */ 
rc = UniQueryLocaleltem (locale_object, LOCI_sLanguageID, 
SmriLanguage) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniQueryLocaleltem error: return code = %u\n", rc) ; 
return 1; 

} 


/* Get the ISO country ID 

rc = UniQueryLocaleltem (locale_object, LOCI_sCountryID, Spinfo) ; 
if (rc ! = ULS_SUCCESS ) { 

printf ("UniQueryLocaleltem error: return code = %u\n", rc) ; 
return 1; 

} 


/* Now we can determine the country name in the proper language */ 
rc = UniQueryCountryName (pinf o, mriLanguage, &countryName ) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniQueryCountryName error: return code = %u\n", rc) ; 
return 1; 

} 


printf ( "Country name is = %ls\n", countryName) ; 

return ULS_SUCCESS; 

} 


UniQueryDigit 

UniQueryDigit queries character attributes. 

Format 
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((include <unidef.h> 


int UniQuery Digit 

(const LocaleObject localeobject, UniChar uc) 


Parameters 

locale object (const LocaleObject) 

A locale object created by UniCreateLocaleObject or NULL. 

uc (UniChar) 

The UniChar character to query. 


Returns 

Return Value (int) - returns 

If the result of the test is true, the function returns 1 . Otherwise, 0 is returned. 

Remarks 

This function provides the functionality of UniCreateAttrObject, UniQueryCharAttr, and 
UniFreeAttrObject as an atomic operation for the invariant attributes. 

The locale may be specified as NULL to indicate default Unicode character attributes 

Related Functions 

• UniQueryAttr 

• UniQueryChar 

• UniQueryCharAttr 

• UniQueryCharType 

• UniQueryCharTypeTable 

Example 


This example shows how to query character attributes. 

((include <stdio.h> 

((include <unidef.h> 
int main (void) { 

Localeobject locale_object = NULL; 

int result = 0; 

int rc = ULS_SUCCESS ; 

UniChar uni_char = L'5'; /* Unicode number 5 character */ 

/iciciciciciciciciciciciciciciciciciciciciciciciciciciciricicicicicicic-k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k J 

/* Assumes LANG environment variable set to a valid locale name, */ 
/* such as fr_FR */ 

l-k'k'k-k-k-k-k'k-k-k-k'k-k-k'k'k'k'k'k-k'k'k-k-k-k-k-k-k-k-k-k'k'k'k'k-k'k-k'k-k-k-k-k-k-k'k'k'k'k'k'k-k-k-k-k'k-k-k-k-k'k'k'k'k'k j 

rc = UniCreateLocaleObject (UNI_UCS_STRING_POINTER, 

(UniChar *)L"", &locale_object) ; 

if (rc ! = ULS SUCCESS) { 


Unicode Functions (OS/2 Warp) 


printf ( "UniCreateLocaleObj ect error: return code = %u\n", rc) ; 
return 1; 

} 

/* * Query character attribute */ 

result = UniQueryDigit (locale_object, uni_char) ; 
if (result) 

printf ( "UniChar character %04X is a digit\n", uni_char) ; 
else 

printf ( "UniChar character %04X is not a digit\n", uni_char) ; 

return ULS_SUCCESS; 

} 


UniQuery Graph 

UniQueryGraph queries character attributes. 

Format 


((include <unidef.h> 


int UniQueryGraph 

(const LocaleObject localeobject, UniChar uc) 


Parameters 

locale object (const LocaleObject) 

A locale object created by UniCreateLocaleObj ect or NULL. 

uc (UniChar) 

The UniChar character to query. 

Returns 

Return Value (int) - returns 

If the result of the test is true, the function returns 1 . Otherwise, 0 is returned. 

Remarks 

This function provides the functionality of UniCreateAttrObject, UniQueryCharAttr, and UniFreeAttrObject 
as an atomic operation for the invariant attributes. 

The locale may be specified as NULL to indicate default Unicode character attributes 

Related Functions 

• UniQueryAttr 

• UniQueryChar 

• UniQueryCharAttr 

• UniQueryCharType 
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• UniQueryCharTypeTable 

Example 


This example shows how to query character attributes. 

((include <stdio.h> 

((include <unidef.h> 
int main (void) { 

LocaleObject locale_object = NULL; 

int result = 0; 

int rc = ULS_SUCCESS ; 

UniChar uni_char = L'S'; /* Unicode Latin uppercase letter S */ 

/itjtjt-k-k-k'k-k-k-k-k'k'k'k'k-k-k-k-k-k-k-k-k'k-k-k-k-k'k'k'k-k-k-k-k-k-k-k-k-k-k-k-k-k'k-k-k'k-k-k-k-k'k'k-k-k-k-k-k-k'k'k'k'k-k J 

/* Assumes LANG environment variable set to a valid locale name, */ 

/* such as fr_FR */ 

/i<j<j<itjtit'k-k-k-k-k'k'k'k'k-k'k'k'k-k-k'k'k-k-k-k-k'k'k'k'k'k-k'k-k-k-k-k-k-k-k-k-k-k-k-k-k'k'k'k'k-k'k'k'k'k-k-k-k-k'k'k'k'k-k J 

rc = UniCreateLocaleObject (UNI_UCS_STRING_PO INTER, 

(UniChar *)L"", &locale_object) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniCreateLocaleObj ect error: return code = %u\n", rc) ; 
return 1; 

} 

/* Query character attribute */ 

result = UniQueryGraph (locale_object, uni_char) ; 
if (result) 

printf ( "UniChar character %04X is a graphic characterin'', uni_char) ; 
else 

printf ( "UniChar character %04X is not a graphic characterin'', uni_char) ; 

return ULS_SUCCESS; 

} 


UniQueryLanguageName 

UniQueryLanguageName returns the name of the language in the language specified. 

Format 


((include <unidef.h> 


int UniQueryLanguageName 

(UniChar * language, UniChar * isolang, UniChar * * infoitem) 


Parameters 

language (UniChar *) 

The two character ID of the language to query, 
isolang (UniChar *) 

The two character ID of the language used to return the language name. 


47 of 154 


Unicode Functions (OS/2 Warp) 


infoitem (UniChar * *) 

A pointer to the language name. 

Returns 

Return Value (int) - returns 

UniQueryLanguageName returns one of the following values: 

ULS_IN VALID 

The language ID supplied is not known. 

0 is returned upon success and the language name has been returned to the caller. 

Remarks 

This function only queries system provided locales to determine valid language names. 

Related Functions 

• UniQueryCountryName 

Example 


This example shows how to query a language name, 
((include <stdio.h> 

((include <unidef.h> 

((include <ulsitem.h> 


int main (void) { 

LocaleObject locale_object = NULL; 
int result = 0; 

int rc = ULS_SUCCESS ; 

UniChar *pinfo; 

UniChar *languageName; 

UniChar *mriLanguage ; 

UniChar uni char = L'5'; 


/* Unicode number 5 


character */ 


I iciciciciciciciciciciciciciciciciricicicicicicicicicicicicicicicicicic'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k J 

/* Assumes LANG environment variable set to a valid locale name, */ 
/* such as fr_FR */ 

j ■k-k-k-k-k-k-k-k-k-k'k'k-k-k-k-k-k'k'k'k'k'k'k'k-k-k'k-k-k-k-k-k-k-k-k-k'k'k'k'k-k-k-k-k'k'k-k-k-k'k'k'k'k'k-k-k-k-k-k'k-k-k-k-k-k J 

rc = UniCreateLocaleObject (UNI_UCS_STRING_POINTER, 

(UniChar *)L"", &locale_object) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniCreateLocaleObj ect error: return code = %u\n", rc) ; 
return 1; 

} 


/* Determine the language to get the language name in */ 
rc = UniQueryLocaleltem (locale_object, LOCI_sLanguageID, 
SmriLanguage) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniQueryLocaleltem error: return code = %u\n", rc) ; 
return 1; 
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/* Get the ISO country ID 

rc = UniQueryLocaleltem (locale_object, LOCI_sLanguageID, &pinfo) ; 
if (rc ! = ULS_SUCCESS ) { 

printf ("UniQueryLocaleltem error: return code = %u\n", rc) ; 
return 1; 

} 

/* Now we can determine the country name in the proper language */ 
rc = UniQueryCountryName (pinf o, mriLanguage, SlanguageName) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniQueryCountryName error: return code = %u\n", rc) ; 
return 1; 

} 


printf ( "Language name is = %ls\n", languageName) ; 

return ULS_SUCCESS; 

} 

UniQueryLocalelnfo 

UniQueryLocalelnfo retrieves information about locale conventions. 

Format 


#include <unidef.h> 


int UniQueryLocalelnfo 

(const LocaleObject localeobject, struct UniLconv **UniLconv_addr_ptr) 


Parameters 

locale object (const LocaleObject) 

A locale object created by UniCreateLocaleObject. 

UniLconv_addr_ptr (struct UniLconv **) 

The address of a pointer to receive a structure filled with locale conventions. 

Returns 

return value (int) - returns 

UniQueryLocalelnfo returns one of the following values: 

ULSSUCCESS 

The UniLconv structure was successfully filled with items associated with the locale object 
localeobject. 

ULSBADOBJ 

The locale object specified by locale object is not a valid locale object. 


Remarks 
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UniQueryLocalelnfo retrieves information from the locale indicated by the locale object argument and places 
the information in a UniLconv structure. UniQueryLocalelnfo allocates memory to hold the UniLconv 
structure. It is the application's responsibility to free the memory with UniFreeLocalelnfo when the UniLconv 
structure is no longer needed. The address of the UniLconv structure is returned in UniLconv struct. The 
UniLconv structure is filled in, according to the locale indicated by the locale object handle argument. 

The UniLconv structure contains the following members: 

UniChar *decimaI_point; 

/* non-monetary decimal point */ 

UniChar *thousands_sep; 

/* non-monetary thousands separator */ 

UniChar *grouping; 

/* non-monetary size of grouping */ 

UniChar *int_curr_symbol; 

/* international currency symbol and separator */ 

UniChar *currency_symbol; 

/* local currency symbol */ 

UniChar *mon_decimal_point; 

/* monetary decimal point */ 

UniChar *mon_thousands_sep; 

/* monetary thousands separator */ 

UniChar *mon_grouping; 

/* monetary size of grouping */ 

UniChar *positive_sign; 

/* non-negative values sign */ 

UniChar *negative_sign; 

/* negative values sign */ 

UniChar int frac digits; 

/* number of fractional digits - int currency */ 

UniChar frac digits; 

/* number of fractional digits - local currency */ 

UniChar p cs precedes; 

/* (non-neg curr sym) 1 -precedes, O-succeeds */ 

UniChar psepbyspace; 

/* (non-neg curr sym) 1 -space, 0-no space */ 

UniChar n cs precedes; 

/* (neg curr sym) 1 -precedes, O-succeeds */ 

UniChar n sep by space; 

/* (neg curr sym) 1 -space, 0-no space */ 

UniChar p signjposn; 

/* positioning of non-negative monetary sign */ 

UniChar n_sign_posn; 

/* positioning of negative monetary sign */ 
short os2_mondecpt; 

/* os2 curr sym positioning */ 

UniChar *debit_sign; 

/* non-negative-valued monetary symbol - "DB"*/ 
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UniChar *credit_sign; 

/* negative-valued monetary symbol - "CR" */ 

UniChar *left_parenthesis; 

/* negative-valued monetary symbol - "(" */ 

UniChar *right_parenthesis; 

/* negative-valued monetary symbol - ")" */ 

The value of grouping and mon grouping is interpreted according to the following: 

Oxffff 

No further grouping is to be performed. 

0x0000 

The previous element is to be repeatedly used for the remainder of the digits. 

other 

The integer value is the number of digits that comprise the current group. 

The next element is examined to determine the size of the next group of digits before the current group. 
The n_sign_posn and p_sign_posn elements are interpreted according to the following: 

0 

Quantity and currency symbol are enclosed in parentheses 

1 

Sign precedes the quantity and currency symbol 

2 

Sign follows the quantity and currency symbol 

3 

Sign precedes the currency symbol 

4 

Sign follows the currency_symbol 

5 

Use debit or credit sign for p_sign_posn or n_sign_posn 

Related Functions 

• UniF reeLocalelnfo 

Example 


This example shows how to retrieve information about locale conventions. 
#include <stdio.h> 

#include <unidef.h> 

int main (void) { 

LocaleObject locale_object = NULL; 

struct UniLconv *puni lconv = NULL; 

int rc = ULS_SUCCESS ; 

/*j<j<ititititj(j(-k-k'k'k'k'k-k'k'k'k-k-k-k-k-k-k-k-k-k'k'k'k'k-k-k-k-k-k'k-k'k-k-k-k-k'k'k'k'k'k'k'k-k-k-k-k'k-k-k-k-k'k'k'k'k-k j 

/* Assumes LANG environment variable set to a valid locale name, */ 
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/* such as fr_FR */ 

/iciciciriciciciciciciciriciririciciciciciciciciciciciciriririricicicic-k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k J 

rc = UniCreateLocaleObject (UNI_UCS_STRING_PO INTER, 

(UniChar *)L"", &locale_object) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniCreateLocaleObj ect error: return code = %u\n", rc) ; 
return 1; 

} 

/* Retrieve locale information */ 

rc = UniQueryLocalelnfo (locale_object, &puni_lconv) ; 
if (rc ! = ULS_SUCCESS ) { 

printf ( "UniQueryLocalelnfo error: return code = %u\n", rc) ; 
return 1; 

} 

/* print the value of the os2 currency symbol position */ 
printf ("The os2 currency symbol position is %d\n", 
puni_lconv->os2_mondecpt ) ; 
return ULS SUCCESS; 


} 


UniQueryLocaleltem 

UniQueryLocaleltem retrieves locale information by item. 

Format 


((include <unidef.h> 


int UniQueryLocaleltem 

(const LocaleObject localeobject, Localeltem item, UniChar **info_item_addr_ptr) 


Parameters 

locale object (const LocaleObject) 

A locale object created by UniCreateLocaleObject. 

item (Localeltem) 

The item to be queried. 


info_item_addr_ptr (UniChar **) 

Address of a pointer where the locale information will be received. 

Returns 

return value (int) - returns 

UniQueryLocaleltem returns one of the following values: 

ULSSUCCESS 

The info_item_addr_ptr string is successfully filled with item associated with the locale object 
localeobject. 

ULS INVALID 
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The locale item is not a valid locale item. 

Remarks 

UniQueryLocaleltem returns a pointer in info_item_addr_ptr to a null-terminated UniChar string containing 
information found in the locale object identified by locale object about the language or cultural item named 
by the item argument. UniQueryLocaleltem allocates the memory to hold the UniChar string and returns a 
pointer in info_item_addr_ptr. Use UniFreeMem to free the memory associated with info_item_addr_ptr by 
UniQueryLocaleltem. 


The constant names and values for item are contained in ulsitem.h: 


Item Name 

Item Description 

LOCI sDateTime 

Date and time format string 

LOCI sShortDate 

Short date format 

LOCI sTimeFormat 

Time format string 

LOCI_sll59 

AM string 

LOCI_s2359 

PM sring 

LOCI sAbbrevDayName7 

Abbreviation of day 7 (Sun) 

LOCI sAbbrevDayNamel 

Abbreviation of day 1 (Mon) 

LOCI sAbbrevDayName2 

Abbreviation of day 2 (Tue) 

LOCI sAbbrevDayName3 

Abbreviation of day 3 (Wed) 

LOCI sAbbrevDayName4 

Abbreviation of day 4 (Thu) 

LOCI sAbbrevDayName5 

Abbreviation of day 5 (Fri) 

LOCI sAbbrevDayName6 

Abbreviation of day 6 (Sat) 

LOCI sDayName7 

Name of day of week 7 (Sun) 

LOCI sDayNamel 

Name of day of week 1 (Mon) 

LOCI sDayName2 

Name of day of week 2 (Tue) 

LOCI sDayName3 

Name of day of week 3 (Wed) 

LOCI sDayName4 

Name of day of week 4 (Thu) 

LOCI sDayName5 

Name of day of week 5 (Fri) 
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LOCI sDayName6 

Name of day of week 6 (Sat) 

LOCI sAbbrevMonthNamel 

Abbreviation of month 1 

LOCI sAbbrevMonthName2 

Abbreviation of month 2 

LOCI sAbbrevMonthName3 

Abbreviation of month 3 

LOCI sAbbrevMonthName4 

Abbreviation of month 4 

LOCI sAbbrevMonthName5 

Abbreviation of month 5 

LOCI sAbbrevMonthName6 

Abbreviation of month 6 

LOCI sAbbrevMonthName7 

Abbreviation of month 7 

LOCI sAbbrevMonthName8 

Abbreviation of month 8 

LOCI sAbbrevMonthName9 

Abbreviation of month 9 

LOCI sAbbrevMonthNamelO 

Abbreviation of month 10 

LOCI sAbbrevMonthNamell 

Abbreviation of month 1 1 

LOCI sAbbrevMonthNamel 2 

Abbreviation of month 12 

LOCI sMonthNamel 

Name of month 1 

LOCI sMonthName2 

Name of month 2 

LOCI sMonthName3 

Name of month 3 

LOCI sMonthName4 

Name of month 4 

LOCI sMonthName5 

Name of month 5 

LOCI sMonthName6 

Name of month 6 

LOCI sMonthName7 

Name of month 7 

LOCI sMonthName8 

Name of month 8 

LOCI sMonthName9 

Name of month 9 

LOCI sMonthNamelO 

Name of month 10 

LOCI sMonthNamell 

Name of month 1 1 

LOCI sMonthNamel 2 

Name of month 12 
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LOCI sDecimal 

Decimal point 

LOCI sThousand 

Triad separator 

LOCI sYesString 

Yes string 

LOCI sNoString 

No string 

LOCIsCurrency 

Currency symbol 

LOCIsCodeSet 

Locale codeset 

LOCI xLocaleToken 

IBM Locale Token 

LOCI xWinLocale 

Win32 Locale ID 

LOCI iLocaleResnum 

Resource number for description 

LOCI sNativeDigits 

String of native digits 

LOCI iMaxItem 

Maximum item number 

LOCI sTimeMark 

Time mark (am/pm) format 

LOCI sEra 

Era definition 

LOCI sAltShortDate 

Alternate short date format string 

LOCI sAltDateTime 

Alternate date and time format 

LOCI sAltTimeFormat 

Alternate time format 

LOCI sAltDigits 

XPG4 alternate digist 

LOCI sYesExpr 

xpg4 yes expression 

LOCI sNoExpr 

xpg4 no expression 

LOCI sDate 

Short date separator 

LOCI sTime 

Time separator 

LOCI sList 

List separator 

LOCI sMonDecimalSep 

Monetary currency separator 

LOCI sMonThousandSep 

Monetary triad separator 

LOCIsGrouping 

Grouping of digits 
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LOCIsMonGrouping 

Monetary groupings 

LOCIiMeasure 

Measurement (Metric, British) 

LOCIiPaper 

Normal paper size 

LOCI iDigits 

Digits to right of decimal 

LOCI iTime 

Clock format 

LOCI iDate 

Format of short date 

LOCIiCurrency 

Format of currency 

LOCI iCurrDigits 

Digits to right for currency 

LOCI iLzero 

Leading zero used 

LOCI iNegNumber 

Format of negative number 

LOCIiLDate 

Format of long date 

LOCIiCalendarType 

Type of default calandar 

LOCI iFirstDayOfWeek 

First day of week (0=Mon) 

LOCI iFirstWeekOfYear 

First week of year 

LOCIiNegCurr 

Format of negative currency 

LOCI iTLzero 

Leading zero on time 

LOCI iTimePreflx 

AM/PM preceeds time 

LOCI iOptionalCalendar 

Alternate calandar type 

LOCI slntlSymbol 

International currency symbol 

LOCI sAbbrevLangName 

Windows language abbreviation 

LOCIsCollate 

Collation table 

LOCIiUpperType 

Upper case algorithm 

LOCIiUpperMissing 

Action for missing upper case 

LOCIsPositiveSign 

Positive sign 

LOCIsNegativeSign 

Negative sign 
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LOCI sLeftNegative 

Left paren for negative 

LOCI sRightNegative 

Right paren for negative 

LOCI sLongDate 

Long date formatting string 

LOCI sAltLongDate 

Alternate long date format string 

LOCI sMonthNamel3 

Name of month 13 

LOCI sAbbrevMonthNamel3 

Abbreviation of month 13 

LOCI sName 

OS/2 locale name 

LOCI sLanguagelD 

Abbreviation for language (ISO) 

LOCI sCountrylD 

Abbreviation for country (ISO) 

LOCIsEngLanguage 

English name of Language 

LOCIsLanguage 

Native name of language 

LOCIsEngCountry 

English name of country 

LOCIsCountry 

Localized country name 

LOCI sNativeCtryName 

Name of country in native language 

LOCI iCountry 

Country code 

LOCIsISOCodepage 

ISO codepage name 

LOCIiAnsiCodepage 

Windows codepage 

LOCIiCodepage 

OS/2 primary codepage 

LOCIiAltCodepage 

OS/2 alternate codepage 

LOCIiMacCodepage 

Mac codepage 

LOCIiEbcdicCodepage 

Ebcdic codepage 

LOCIsOtherCodepages 

Other ASCII codepages 

LOCIsSetCodepage 

Codpage to set on activation 

LOCIsKeyboard 

Primary keyboard name 

LOCI sAltKeyboard 

Alternate keyboard name 
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LOCIsSetKeyboard 

Keyboard to set on activation 

LOCIsDebit 

Debit string 

LOCIsCredit 

Credit string 

LOCI sLatinl Locale 

Locale for Latin 1 names 

LOCI wTimeFormat 

Win32 Time format 

LOCI wShortDate 

Win32 Date format 

LOCIwLongDate 

Win32 Long date format 



Related Functions 

• UniSetUserLocaleltem 


Example 


This example shows how to retrieve locale information by item. 

#include <stdio.h> 

((include <unidef.h> 

int main (void) { 

LocaleObject locale_object = NULL; 

UniChar *pinfo_item; 

int rc = ULS_SUCCESS ; 

/-k'k'k-k-k'k-k-k-k-k-k'k'k'k'k-k'k'k'k-k-k-k-k-k-k-k-k-k'k'k-k'k'k'k'k-k-k'k-k'k'k'k'k-k-k-k-k'k'k'k'k-k-k-k-k'k-k-k-k-k-k-k-k'k'k j 

/* Assumes LANG environment variable set to a valid locale name, */ 
/* such as fr_FR */ 

/iciciciciciciciciciciciririciriciciciciciciciciciciciciciciriricicic-k'k'k'k'k'k'k'k-k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k J 

rc = UniCreateLocaleObject (UNI_UCS_STRING_PO INTER, 

(UniChar *)L"", &locale_object) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniCreateLocaleObj ect error: return code = %u\n", rc) ; 
return 1; 

} 

/* Retrieve name of the tenth month locale item */ 
rc = UniQueryLocaleltem (locale_object, 

MON_ 1 0 , 

&pinfo_item) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniQueryLocaleltem error: return code = %u\n", rc) ; 
return 1; 

} 

rc = UniFreeMem (pinfo_item) ; 
if (rc ! = ULS_SUCCESS ) { 

printf ( "UniFreeMem error: return code = %u\n", rc) ; 
return 1; 

} 

return ULS_SUCCESS; 

} 
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UniQueryLocaleList 

UniQueryLocaleList returns a buffer filled with a list of the locales defined on the system. 

Format 


#include <unidef.h> 


int UniQueryLocaleList 

(int flag, UniChar * uniBuffer, int numUniChars) 


Parameters 

flag (int) 

A flag indicating whether to return a list of system defined locales or user defined locales. 
uniBuffer (UniChar * ) 

A pointer to a buffer that is filled with UniChar's representing the list of system or user defined locales. 
numUniChars (int) 

The maximum size of the buffer used to return the list of locales. 

Returns 

return value (int) - returns 

UniQueryLocaleList returns one of the following values: 

ULS_SUCCESS 

The buffer is filled with the appropriate list of locales. 

ULSBUFFERFULL 

The locale list size exceeded the supplied buffer size. 


Remarks 

The flag parameter can be used to select either system defined locales or user defined locales. The system and 
user defined choices can be or’ed together to retrieve the complete list of locales. 

Related Functions 

• UniQueryLocaleValue 

Example 


This example shows how to retrieve a list of locales available on the 
system. 

#include <stdio.h> 

#include <unidef.h> 
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int main (void) { 

int rc = ULS_SUCCESS ; 

/* Arrays containing system and user locales */ 

UniChar *uniSysLocales ; 

UniChar *uniUsrLocales ; 

/* Allocate space for the locale list (2 bytes/UniChar ) */ 
uniSysLocales = (UniChar *) malloc (4096) ; 
uniUsrLocales = (UniChar *) malloc (4096) ; 

if (! uniSysLocales | | ! uniUsrLocales ) { 

printf ( "Malloc failed error: return code = %u\n", rc) ; 
return 1; 

} 


j 'k'k'k'k-k-k-k-k'k'k'k'k-k-k-k-k'k'k'k'k-k'k'k-k-k-k-k-k-k-k-k-k'k'k'k'k'k-k-k-k-k-k-k'k-k-k-k-k'k'k'k'k'k'k'k'k-k-k-k-k j 

/* Obtain the list of system and user defined locales */ 

j k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k j 

rc = UniQueryLocaleList (UNI__SYSTEM_LOCALES, uniSysLocales, 2048); 
if (rc) { 

printf ( "UniQueryLocaleList error: return code = %u\n", rc) ; 
return 1; 


rc = UniQueryLocaleList (UNI_USER_LOCALES, uniUsrLocales, 2048); 
if (rc) { 

printf ( "UniQueryLocaleList error: return code = %u\n", rc) ; 
return 1; 

} 

return ULS SUCCESS; 


} 


UniQueryLocaleObi ect 

UniQueryLocaleObject retrieves the locale name. 

Format 


((include <unidef.h> 


int UniQueryLocaleObject 

(const LocaleObject locale object, int category, int LocaleSpecType, void **locale_name) 


Parameters 

locale object (const LocaleObject) 

Locale object created by a call to UniCreateLocaleObject. 

category (int) 
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Locale category identifier. 


The permissible values for category are: 

• LCALL 

• LCCOLLATE 

• LCCTYPE 

• LCMESSAGES 

• LCMONETARY 

• LCNUMERIC 

• LC TIME 


LocaleSpecType (int) 

The LocaleSpecType argument can take any of the following values, which are constants defined in the 
header unidef.h: 

UNI_TOKEN_POINTER 

Requests that a pointer to a token pointer be returned. 

UNIMBSSTRINGPOINTER 

Requests that a multibyte string pointer be returned. 

UNIU C SSTRIN GPOINTER 

Requests that a UCS string pointer be returned. 


localename (void **) 

The address of a pointer variable locale name that will contain the locale name. 

Returns 

return value (int) - returns 

UniQueryLocaleObject returns one of the following values: 

ULSSUCCESS 

A valid locale specification for the supplied locale object is returned. 

ULSIN VALID 

The locale specified by locale object is invalid. 

ULSOTHER 

The C locale is because LOCALE.DLL cound not be found. 

ULSJJNSUPPORTED 

The locale name is valid but the locale cound not be found. 


Remarks 

UniQueryLocaleObject returns a pointer to a locale specification in the area pointed to by locale_name. 
UniQueryLocaleObject allocates memory to hold the generated value as necessary. Use UniFreeMem to free 
the memory associated with locale name by UniQueryLocaleObject. 

The value returned in the area pointed to by locale_name will point to either a string or a token, as indicated 
by the value of the LocaleSpecType argument. 
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When the LocaleSpecType argument is UNI_TOKEN_POINTER and the category argument is valid, a 
pointer to a token that represents the locale value associated with the category argument is returned, if such a 
token exists. 

When the LocaleSpecType argument is UNI_MBS_STRING_POINTER or 

UNI_UCS_STRING_POINTER, UniQueryLocaleObject returns a pointer to a string that represents the 
locale value associated with the category argument. 

When the LocaleSpecType argument is UNI_MBS_STRING_POINTER or 

UNI_UCS_STRING_POINTER and the category argument is LC_ALL, a string that represents the values 
of all of the locale categories of localeobject is returned. The returned string may be used as the LocaleSpec 
argument to UniCreateLocaleObject to create a locale object that is a functional equivalent of locale object. 

When the LocaleSpecType argument is UNI_MBS_STRING_POINTER or 

UNI U C S STRIN G POINTER and the category argument is LC COLLATE, LC_CTYPE, 

LC MESSAGES, LC MONETARY, LC_NUMERIC, or LC TIME, a string that represents the value of 
the respective locale category of locale object is returned. The returned string may be used as the 
LocaleSpec argument to UniCreateLocaleObject create a locale object. All locale category values are set to 
the value of the queried locale category of locale object. 

If locale object contains a NULL pointer, UniQueryLocaleObject returns a locale specification pointer 
identifying the respective categories of the default locale. If the category argument is LC_ALL, this value 
can be passed to UniCreateLocaleObject to create a locale object that is the functional equivalent of the 
current default locale, as specified by the environment variables of the current process. 

If locale object is invalid, the contents of locale name are undefined and no memory is allocated. 

Related Functions 

• UniCreateLocaleObi ect 

• UniFreeLocaleObi ect 

Example 


This example shows how to retrieve a locale category name. 

#include <stdio.h> 

#include <unidef.h> 
int main (void) { 

Localeobject locale_object = NULL; 

UniChar *plocale_name; 

int rc = ULS_SUCCESS ; 

/* Retrieve locale name of default locale */ 

rc = UniQueryLocaleObject (NULL, 

LC_ALL , 

UN I_UCS_STRING_PO INTER, 

(void **) &plocale_name ) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ("UniQueryLocaleObject error: return code = %u\n", rc) ; 
return 1; 
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/* Create a locale object based upon the default setting */ 
rc = UniCreateLocaleObject (UNI_UCS_STRING_PO INTER, 

(UniChar * ) plocale_name, &locale_object) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniCreateLocaleObj ect error: return code = %u\n", rc) ; 
return 1; 

} 

rc = UniFreeMem (plocale_name ) ; 
if (rc ! = ULS_SUCCESS ) { 

printf ( "UniFreeMem error: return code = %u\n", rc) ; 
return 1; 

} 

return ULS SUCCESS; 


} 


UniQueryLocale Value 

UniQueryLocaleValue returns an integral value associated with the requested locale item. 

Format 


((include <unidef.h> 


int UniQueryLocaleValue 

(const LocaleObject localeobject, Localeltem item, int * infoitem) 


Parameters 


locale object (const LocaleObject) 

Locale object created by a call to UniCreateLocaleObject. 


item (Localeltem) 

The locale item being requested. 


info item (int *) 

A pointer to an integer where the value of the locale item is returned. 

Returns 


return value (int) - returns 

UniQueryLocaleValue returns one of the following values: 
ULS_SUCCESS 

The info item is set to the appropriate integral item value. 

ULSBADOBJ 

The locale item is invalid or does not exist. 


Remarks 
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When a locale item is requested that does not have an integral value, zero is returned to the caller. 

Related Functions 

• UniQueryLocaleList 

Example 


This example shows how to retrieve the value for a locale item, 
((include <stdio.h> 


((include <unidef.h> 
((include <ulsitem.h> 


int main (void) { 


LocaleObject locale_object = NULL; 
ULONG pmCodepage; 

int result = 0; 


int rc = ULS_SUCCESS ; 

UniChar uni char = L'd'; /* Unicode lowercase Latin letter d */ 

I • k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k J 


/* Assumes LANG environment variable set to a valid locale name, */ 
/* such as fr_FR */ 

liciciciciciciciciciciciciciciciciciciciriciciciciciciciricicicicicicic-k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k J 


rc = UniCreateLocaleObject (UNI_UCS_STRING_PO INTER, 

(UniChar *)L"", &locale_object) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniCreateLocaleObj ect error: return code = %u\n", rc) ; 
return 1; 


rc = UniQueryLocaleValue (locale_object, LOCI_iCodepage, 

(int *) & pmCodepage) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniQueryLocaleValue error: return code = %u\n", rc) ; 
return 1; 

} 


printf (" Presentation manager is using codepage %d\n", 
pmCodepage) ; 

return ULS SUCCESS; 


} 


UniQueryLower 

UniQueryLower queries character attributes. 

Format 


((include <unidef.h> 


int UniQueryLower 
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(const LocaleObject localeobject, UniChar uc) 


Parameters 

locale object (const LocaleObject) 

A locale object created by UniCreateLocaleObject or NULL, 
uc (UniChar) 

The UniChar character to query. 

Returns 

Return Value (int) - returns 

If the result of the test is true, the function returns 1 . Otherwise, 0 is returned. 

Remarks 

This function provides the functionality of UniCreateAttrObject UniQueryCharAttr, and UniFreeAttrObject as 
an atomic operation for the invariant attributes. 

The locale may be specified as NULL to indicate default Unicode character attributes 

Related Functions 

• UniQueryAttr 

• UniQueryChar 

• UniQueryCharAttr 

• UniQueryCharType 

• UniQueryCharTypeTable 

Example 


This example shows how to query character attributes. 

((include <stdio.h> 

((include <unidef.h> 
int main (void) { 

Localeobject locale_object = NULL; 

int result = 0; 

int rc = ULS_SUCCESS ; 

UniChar uni char = L'd'; /* Unicode lowercase Latin letter d */ 

/iciciciciciciciciciciciciriririciciciciciciciciciciciciriririricicicic-k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k J 

/* Assumes LANG environment variable set to a valid locale name, */ 

/* such as fr_FR */ 

I iciciciciciciciciciciciciciririciciciciciciciciciciciciriririricicicic'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k J 

rc = UniCreateLocaleObject (UNI_UCS_STRING_POINTER, 

(UniChar *)L"", &locale_object) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniCreateLocaleObj ect error: return code = %u\n", rc) ; 
return 1; 

} 

/* Query character attribute */ 

result = UniQueryLower (locale_object, uni_char) ; 
if (result) 

printf ( "UniChar character %04X is a lowercase characterin'', uni char); 
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else 

printf ( "UniChar character %04X is not a lowercase character\n" , uni_char) ; 

return ULS_SUCCESS; 

} 


UniQueryNumeric Value 

UniQueryNumeric Value returns the numeric value associated with a Unicode character. 

Format 


((include <unidef.h> 


int UniQueryNumeric Value 
(UniChar uc) 


Parameters 

uc (UniChar) 

The UniChar character to query. 

Returns 

Return Value (int) - returns 

The function returns a - 1 if unsuccessful. Otherwise, the numeric value of the Unicode character is 
returned. 

Remarks 

This function returns numeric values for ranges of Unicode numeric characters. The function can be used to 
identify the digits both decimal and hexadecimal for Latin numbers, Arabic, Indian dialects, Laotian, Thai, 
Han and others represented in the Unicode character set. 

Related Functions 

• UniQueryCharType 

Example 


This example shows how to query the numeric value of a character, 
((include <stdio.h> 


((include <unidef.h> 
int main (void) { 


int 

int 

UNICTYPE 

UniChar 


result = 0; 

rc = ULS_SUCCESS ; 

* ct; 

* uptr; 
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/* Set up a Unicode numeric character to test */ 
uptr = L ' 1 ' ; 

/* Determine the characters type */ 
ct = UniQueryCharType ( *uptr ) ; 

/* Test the Unicode character to see if it is a digit */ 

/* It can be either decimal or Hex */ 

if ( (ct->itype & CT_XDIGIT) || (ct->itype & CT_NUMBER) ) { 

num = UniQueryNumericValue (*uptr) ; 

if (num == -1) { 

printf ( "UniQueryNumericValue error: return code = %u\n", rc) ; 
return 1; 

} 

return ULS SUCCESS; 


UniQueryPrint 

UniQueryPrint queries character attributes. 

Format . 


((include <unidef.h> 


int UniQueryPrint 

(const LocaleObject localeobject, UniChar uc) 


Parameters 

locale object (const LocaleObject) 

A locale object created by UniCreateLocaleObject or NULL. 

uc (UniChar) 

The UniChar character to query. 

Returns 

Return Value (int) - returns 

If the result of the test is true, the function returns 1 . Otherwise, 0 is returned. 

Remarks 

This function provides the functionality of UniCreateAttrObject, UniQueryCharAttr, and UniFreeAttrObject 
as an atomic operation for the invariant attributes. 

The locale may be specified as NULL to indicate default Unicode character attributes 

Related Functions 
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• UniQueryAttr 

• UniQueryChar 

• UniQueryCharAttr 

• UniQueryCharType 

• UniQueryCharTypeTable 

Example 


This example shows how to query character attributes. 

((include <stdio.h> 

((include <unidef.h> 
int main (void) { 

LocaleObject locale_object = NULL; 

int result = 0; 

int rc = ULS_SUCCESS ; 

UniChar uni_char = L'd'; /* Unicode lowercase Latin letter d */ 

/iciciciciciciciciciciciriciririciciciciciciciciciciciciriciciricicicic-k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k J 

/* Assumes LANG environment variable set to a valid locale name, */ 

/* such as fr_FR */ 

/itititititjf-k-k-k-k-k'k'k'k'k-k-k-k-k-k'k'k-k-k-k-k-k-k'k'k'k-k-k-k-k-k-k-k-k-k-k-k-k'k'k'k'k'k-k-k-k-k-k-k-k-k-k-k-k'k'k'k'k'k-k j 

rc = UniCreateLocaleObject (UNI_UCS_STRING_PO INTER, 

(UniChar *)L"", &locale_object) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniCreateLocaleObj ect error: return code = %u\n", rc) ; 
return 1; 

} 

/* Query character attribute */ 

result = UniQueryPrint (locale_object, uni_char) ; 
if (result) 

printf ( "UniChar character %04X is a printable characterin'', uni char) ; 
else 

printf ( "UniChar character %04X is not a printable characterin'', uni_char) ; 

return ULS_SUCCESS; 

} 


UniQueryPunct 

UniQueryPunct queries character attributes. 

Format 


((include <unidef.h> 


int UniQueryPunct 

(const LocaleObject locale object, UniChar uc) 


Parameters 

locale object (const LocaleObject) 

A locale object created by UniCreateLocaleObject or NULL. 
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uc (UniChar) 

The UniChar character to query. 

Returns 

Return Value (int) - returns 

If the result of the test is true, the function returns 1 . Otherwise, 0 is returned. 

Remarks 

This function provides the functionality of UniCreateAttrObject, UniQueryCharAttr, and UniFreeAttrObject 
as an atomic operation for the invariant attributes. 

The locale may be specified as NULL to indicate default Unicode character attributes 

Related Functions 

• UniQueryAttr 

• UniQueryChar 

• UniQueryCharAttr 

• UniQueryCharType 

• UniQueryCharTypeTable 

Example 


This example shows how to query character attributes. 

((include <stdio.h> 

((include <unidef.h> 
int main (void) { 

LocaleObject locale_object = NULL; 

int result = 0; 

int rc = ULS_SUCCESS ; 

UniChar uni_char = L'?'; /* Unicode Latin question mark */ 

/•k'k'k-k-k-k-k'k'k-k-k'k-k'k'k-k-k-k-k-k-k'k'k'k-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k'k-k-k-k-k'k'k'k-k-k-k-k-k-k-k-k'k'k-k-k-k-k-k-k'k'k J 

/* Assumes LANG environment variable set to a valid locale name, */ 

/* such as fr_FR */ 

jiciciciciciciciciciciciciciciriciciciciciciciciciciciciriciciricicic-k'k'k'k'k-k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k J 

rc = UniCreateLocaleObject (UNI_UCS_STRING_PO INTER, 

(UniChar *)L"", &locale_object) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniCreateLocaleObj ect error: return code = %u\n", rc) ; 
return 1; 

} 

/* Query character attribute */ 

result = UniQueryPrint (locale_object, uni_char) ; 
if (result) 

printf ( "UniChar character %04X is a punctuation characterin'', uni_char) ; 
else 

printf ( "UniChar character %04X is not a punctuation characterin'', uni_char) ; 

return ULS_SUCCESS; 

} 
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UniQuerySpace 

UniQuerySpace queries character attributes. 

Format 


((include <unidef.h> 


int UniQuerySpace 

(const LocaleObject localeobject, UniChar uc) 


Parameters 

locale object (const LocaleObject) 

A locale object created by UniCreateLocaleObject or NULL. 

uc (UniChar) 

The UniChar character to query. 

Returns 

Return Value (int) - returns 

If the result of the test is true, the function returns 1 . Otherwise, 0 is returned. 

Remarks 

This function provides the functionality of UniCreateAttrObject, UniQueryCharAttr, and UniFreeAttrObject 
as an atomic operation for the invariant attributes. 

The locale may be specified as NULL to indicate default Unicode character attributes 

Related Functions 

• UniQueryAttr 

• UniQueryChar 

• UniQueryCharAttr 

• UniQueryCharType 

• UniQueryCharTypeTable 

Example 


This example shows how to query character attributes. 

((include <stdio.h> 

((include <unidef.h> 
int main (void) { 

Localeobject locale_object = NULL; 

int result = 0; 

int rc = ULS_SUCCESS ; 

UniChar uni_char = L' /* Unicode space character */ 
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/•k'k'k-k-k'k-k-k-k-k-k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k'k'k'k-k-k-k-k-k-k-k'k'k'k J 

/* Assumes LANG environment variable set to a valid locale name, */ 

/* such as fr_FR */ 

jiciciciciciciciciciciciciciririciciciciciciciciciciciciriririricicicic'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k J 

rc = UniCreateLocaleObject (UNI_UCS_STRING_PO INTER, 

(UniChar *)L"", &locale_object) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniCreateLocaleObj ect error: return code = %u\n", rc) ; 
return 1; 

} 

/* Query character attribute */ 

result = UniQuerySpace (locale_object, uni_char) ; 
if (result) 

printf ( "UniChar character %04X is a space characterin'', uni char); 
else 

printf ( "UniChar character %04X is not a space characterin'', uni char); 

return ULS_SUCCESS; 

} 


UniQueryStringType 

UniQueryStringType is used to query character types for a string. 

Format 


((include <unidef.h> 


ULONG UniQueryStringType 

(UniChar * ustr, int size, USHORT * outstr, int kind) 


Parameters 

ustr (UniChar *) 

A pointer to the Unicode string. 


size (int) 

The size of the UniChar character string to query. 


outstr (USHORT *) 

A pointer to an array of USHORTs. Each USHORT represents the type of one of the Unicode 
characters. 


kind (int) 

An integer describing the type of string. 

Returns 


Return Value (ulong) - UniQueryStringType returns one of the following: 
ULS SUCCESS 
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The function was successful. 

ULSINVALID 

The kind of string supplied is not known. 

Remarks 


Valid values for kind are: 

• CTITYPE 

• CTBIDI 

• CTCHARSET 

• CTEXTENDED 

• CTCODEPAGE 

• CTINDEX 

• CT CTYPEl - Win32 compatible XPG/4 

• CTCTYPE2 - Win32 compatible BiDi 

• CT CTYPE3 - Win32 compatible extended 

Related Functions 

• UniQueryCharType 

• UniQueryCharTypeTable 

Example 


This example shows how to query string types. 

((include <unidef.h> 

((include <stdlib.h> 

/* * 

* Count Japanese : Count the number of Japanese chars in string 

* / 

int Count Japanese (UniChar * instr) { 
int len; 

USHORT * outbuf, * pout; 
int count; 

/* 

* Get some memory to return the string 
*/ 

len = UniStrlen (instr) ; 

outbuf = malloc(len * sizeof (UniChar) ) ; 

/* 

* Query the extended character type of the string 
*/ 

UniQueryStringType (instr, len, outbuf, CT_EXTENDED) ; 

/* 

* Search the retuned array of types for Japanese chars 
*/ 

count = 0; 
pout = outbuf; 
while (len--) { 

if (*pout & (C3_KATAKANA| C3_HIRAGANA| C3_IDEOGRAPH) ) { 

count+t; 
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} 

pout++; 


/* * 

* Free up type array and return 
*/ 

free (outbuf ) ; 
return count; 

} 


UniQueryUpper 

UniQueryUpper queries character attributes. 

Format 


((include <unidef.h> 


int UniQueryUpper 

(const LocaleObject localeobject, UniChar uc) 


Parameters 

locale object (const LocaleObject) 

A locale object created by UniCreateLocaleObject or NULL. 

uc (UniChar) 

The UniChar character to query. 

Returns 

Return Value (int) - returns 

If the result of the test is true, the function returns 1 . Otherwise, 0 is returned. 

Remarks 

This function provides the functionality of UniCreateAttrObject, UniQueryCharAttr, and UniFreeAttrObject 
as an atomic operation for the invariant attributes. 

The locale may be specified as NULL to indicate default Unicode character attributes 

Related Functions 

• UniQueryAttr 

• UniQueryChar 

• UniQueryCharAttr 

• UniQueryCharType 

• UniQueryCharTypeTable 
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Example 


This example shows how to query character attributes. 

((include <stdio.h> 

((include <unidef.h> 
int main (void) { 

LocaleObject locale_object = NULL; 

int result = 0; 

int rc = ULS_SUCCESS ; 

UniChar uni_char = L'D'; /* Unicode uppercase Latin letter D */ 

/iciciciciciciciciciciciciriririciciciciciciciciciciciciciciciricicic-k'k'k'k'k-k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k J 

/* Assumes LANG environment variable set to a valid locale name, */ 

/* such as fr_FR */ 

/i<j(*itjtjtjfj<j(j<j<'k'k-k'k-k-k-k-k-k-k-k'k-k-k-k-k-k'k'k'k-k-k-k-k-k-k'k'k'k-k-k-k-k'k'k'k'k-k-k-k-k'k'k'k-k-k-k-k-k'k'k'k'k-k j 

rc = UniCreateLocaleObject (UNI_UCS_STRING_PO INTER, 

(UniChar *)L"", &locale_object) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniCreateLocaleObj ect error: return code = %u\n", rc) ; 
return 1; 

} 

/* Query character attribute */ 

result = UniQueryUpper (locale_object, uni_char) ; 
if (result) 

printf ( "UniChar character %04X is an uppercase characterin'', uni_char) ; 
else 

printf ( "UniChar character %04X is not an uppercase characterin'', uni_char) ; 

return ULS_SUCCESS; 

} 


UniQueryXdigit 

UniQueryXdigit queries character attributes. 

Format 


((include <unidef.h> 


int UniQueryXdigit 

(const LocaleObject locale object, UniChar uc) 


Parameters 

locale object (const LocaleObject) 

A locale object created by UniCreateLocaleObject or NULL. 

uc (UniChar) 

The UniChar character to query. 

Returns 
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Return Value (int) - returns 

If the result of the test is true, the function returns 1 . Otherwise, 0 is returned. 

Remarks 

This function provides the functionality of UniCreateAttrObject, UniQueryCharAttr, and UniFreeAttrObject 
as an atomic operation for the invariant attributes. 

The locale may be specified as NULL to indicate default Unicode character attributes 

Related Functions 

• UniQueryAttr 

• UniQueryChar 

• UniQueryCharAttr 

• UniQueryCharType 

• UniQueryCharTypeTable 

Example 


This example shows how to query character attributes. 

((include <stdio.h> 

((include <unidef.h> 
int main (void) { 

LocaleObject locale_object = NULL; 

int result = 0; 

int rc = ULS_SUCCESS ; 

UniChar uni_char = L'D'; /* Unicode uppercase Latin letter D */ 

/iciciciciciciciciciciciciciriciciciciciciciciciciciciciriririricicicic'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k J 

/* Assumes LANG environment variable set to a valid locale name, */ 
/* such as fr_FR */ 

! k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k J 

rc = UniCreateLocaleObject (UNI_UCS_STRING_PO INTER, 

(UniChar *)L"", &locale_object) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniCreateLocaleObj ect error: return code = %u\n", rc) ; 
return 1; 

} 

/* Query character attribute */ 

result = UniQueryXdigit (locale_object, uni_char) ; 
if (result) 

printf ( "UniChar character %04X is a hex digit\n", uni_char) ; 
else 

printf ( "UniChar character %04X is not a hex digit\n", uni_char) ; 

return ULS_SUCCESS; 

} 


UniScanForAttr 


UniScanForAttr scans a Unicode string for an attribute match. 
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Format 


((include <unidef.h> 

int UniScanForAttr 

(AttrObject attrobject, const UniChar *ucs, sizet numelems, ulsBool inverseop, sizet *offset) 


Parameters 

attr object (AttrObject) 

An attribute object created by UniCreateAttrObject. 
ucs (const UniChar *) 

The array of UniChar code elements to be scanned for the set of attributes in attrobject. 
num elems (size t) 

The number of UniChar code elements to be searched, 
inverse op (ulsBool) 

Determines scanning rules. Set to false to search for the first match. Set to true to search for the first 
nonmatching element, 
offset (size_t *) 

An integer identifying the location of the first element meeting the criteria. 

Returns 

return value (int) - returns 

UniScanForAttr returns one of the following: 

ULSSUCCESS 

The function was successful. 

ULSNOMATCH 

No code element meets the specified criteria. 

ULSBADOBJ 

The attribute object specified by attr object is not a valid attribute object. 

Remarks 

UniScanForAttr scans the array of code elements identified by ucs, from the position specified by ucs, 
searching for the first code element that matches or does not match the set of attributes specified by 
attr_object. 

The inverse op argument determines the rules for scanning and is an integer type containing one of the 
following values: 

0 - FALSE 

1 - TRUE 

If inverse op is set to FALSE, the function searches for the first code element that matches all of the attributes 
of the specified attr object; if inverse op is set to TRUE, the function searches for the first code element that 
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matches none of the attributes of attrobject. 

The search begins from the code element identified by ucs, through the next numelems code elements. A 
non-negative integer identifying the location of the first code element meeting all of the criteria specified by 
attr object is returned in the area pointed to by offset. This indicates the number of code elements offset from 
the code element identified by ucs, to the code element at which the attribute match is satisfied. If no code 
element meets the specified criteria, the contents of offset are undefined. 

Related Functions 

• UniQueryAttr 

• UniQueryChar 

• UniQueryCharAttr 

• UniQueryCharType 

• UniQueryCharTypeTable 

Example 


This example shows how to scan a Unicode string for an attribute match, 
((include <stdio.h> 


((include <unidef.h> 
int main (void) { 

LocaleObject locale_object = NULL; 


AttrObject attr_object = NULL; 

int result = 0; 

int rc = ULS_SUCCESS ; 

size_t offset = 0; 

UniChar *uni_char = L"os2"; 

/iciciciciciciciciciciciriciririciciciciciciciciciciciciciciciricic-k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k 

/* Assumes LANG environment variable set to a valid locale name, 
/* such as fr_FR 

/*j<j<i?-k-k-k-k-k-k-k'k'k'k'k'k-k-k'k-k'k'k'k-k-k-k-k-k'k'k-k'k-k-k'k-k-k'k-k'k-k-k'k'k'k'k-k'k'k'k'k-k-k-k-k-k-k-k'k'k'k'k-k-k 


*/ 

*/ 

*/ 

*/ 


rc = UniCreateLocaleObject (UNI_UCS_STRING_PO INTER, 

(UniChar *)L"", &locale_object) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniCreateLocaleObj ect error: return code = %u\n", rc) ; 
return 1; 


/* Create an attribute object */ 

rc = UniCreateAttrObject (locale_object, 

(UniChar *)L"digit", &attr_object) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniCreateAttrObject error: return code = %u\n", rc) ; 
return 1; 

} 

/* Make call to determine if string matches attributes */ 

rc = UniScanForAttr (attr_object, uni^char, UniStrlen (uni^char) , 

FALSE, soffset) ; 
if (rc ! = ULS_SUCCESS ) { 

printf ( "UniScanForAttr error: return code = %u\n", rc) ; 
return 1; 


return ULS SUCCESS; 
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U niSetU serLocaleltem 

UniSetUserLocaleltem is used to set a locale override for a locale item. 

Format 


#include <unidef.h> 

int UniSetUserLocaleltem 

(UniChar * locale, int item, int type, void * value) 


Parameters 

locale (UniChar *) 

Locale to have item changed. 

item (int) 

Item to be set. 

type (int) 

Type of item. 

value (void *) 

Pointer to item to be changed. 

Returns 

return value (int) - returns 

UniSetUserLocaleltem returns one of the following: 

ULSSUCCESS 

The function was successful. 

ULSINVALID 

No code element meets the specified criteria. 

ULSNOMATCH 

The specified locale was not found. 

UL S_N OMEMORY 

A memory allocation error was detected. 

ULSBADOBJECT 

The specified locale is not a user defined locale. 

UL SBUFFERFULL 

The item is too long for the buffer. 

Remarks 

UniSetUserLocaleltem modifies an item in a user locale. This affects all users of that locale. After doing this 
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function, a call to UniCompleteUserLocale is necessary to make the changes pennanent. 

Related Functions 

• UniQueryLocaleltem 

• UniCompleteUserLocale 

Example 


This example shows how to set a user locale item, 
((include <stdio.h> 

((include <unidef.h> 
int main (void) { 

UniChar unilocaleName [ John ' s_Locale] ; 

LocaleObject locale_object = NULL; 


int result = 0; 

int rc = ULS_SUCCESS ; 

size t offset = 0 ; 


/iciciciciciciciciciciciriciririciciciciciciciciciciciciriririricicicic'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k J 

/* Assumes LANG environment variable set to a valid locale name, */ 
/* such as fr_FR */ 

I'k'k'k-k-k-k-k'k-k-k-k-k-k-k'k'k-k-k-k-k-k-k'k-k-k-k-k-k'k'k'k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k'k'k-k-k'k-k'k'k-k'k'k J 

rc = UniCreateLocaleObject (UNI_UCS_STRING_PO INTER, 

(UniChar *)L"", &locale_object) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniCreateLocaleObj ect error: return code = %u\n", rc) ; 
return 1; 

} 


/* Set the time separator for John's locale to a semicolon */ 
rc = UniSetUserLocaleltem (unilocaleName, TIMESEP, 
ULTYPEJJNICODE, (UniChar *)L":"); 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniSetUserLocaleltem error: return code = %u\n", rc) ; 
return 1; 

} 

return ULS SUCCESS; 


UniStrcat 


UniStrcat concatenates code element strings. 

Format 


((include <unidef.h> 
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UniChar *UniStrcat 

(UniChar *ucsl, const UniChar *ucs2) 


Parameters 

ucsl (UniChar*) 

String to be appended to. 

ucs2 (const UniChar *) 

String to concatenate. 

Returns 

return value (UniChar *) - returns 
Concatenated string. 

Remarks 

UniStrcat appends a copy of the code element string pointed to by ucs2 (including the terminating null code 
element) to the end of the code element string pointed to by ucsl. The initial wide code element of ucs2 
overwrites the null code element at the end of ucsl. If copying takes place between objects that overlap, the 
results are unpredictable. 

Related Functions 

• UniStmcat 

Example 


This example shows how to concatenate Unicode strings . 
((include <stdio.h> 

((include <unidef.h> 
int main (void) { 

UniChar ucsl [40] = L"computer"; 

UniChar *puni; 

puni = UniStrcat (ucs 1 , (UniChar *)L" program"); 
return (ULS_SUCCESS) ; 

} 


UniStrchr 


UniStrchr searches for the first occurrence of a code element. 

Format 


((include <unidef.h> 
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UniChar *UniStrchr 

(const UniChar *ucs, UniChar uc) 


Parameters 

ucs (const UniChar *) 

A null-terminated UniChar string to be searched, 
uc (UniChar) 

The UniChar search character. 

Returns 

return value (UniChar *) - returns 

UniStrchr returns either a pointer to the located code element or a null pointer, if the code element does 
not occur in the string. 

Remarks 

UniStrchr locates the first occurrence of uc in the array of code elements pointed to by ucs. The tenninating 
null code element is considered to be part of the string. 

Related Functions 

• UniStrrchr 

Example 


This example shows how to search a Unicode string for the first occurence 
of a code element. 

((include <stdio.h> 

((include <unidef.h> 
int main (void) { 

UniChar ucsl[] = L"computer program"; 

UniChar *puni; 

UniChar uni_char = L'p'; 

puni = UniStrchr (ucs 1 , uni_char) ; 
if (puni) { 

printffThe character was found in the string\n"); 
return (ULS_SUCCESS) ; 

} 

} 


UniStrcmp 

UniStrcmp compares code element strings. 

Format 
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((include <unidef.h> 


int UniStrcmp 

(const UniChar *ucsl, const UniChar *ucs2) 


Parameters 

ucsl (const UniChar *) 

String to be compared. 

ucs2 (const UniChar *) 

String to be compared. 

Returns 

return value (int) - returns 

UniStrcmp returns an integer greater than, equal to, or less than zero, according to whether the code 
element string pointed to by ucsl is greater than, equal to, or less than the code element string pointed 
to by ucs2. 

Remarks 

UniStrcmp compares the code element string pointed to by ucsl to the code element string pointed to by ucs2. 

Related Functions 

• UniStrcmpi 

• UniStrncmp 

• Unistmcmpi 

Example 


This example shows how to compare Unicode strings . 
((include <stdio.h> 

((include <unidef.h> 
int main (void) { 

UniChar ucsl[] = L"computer"; 

UniChar ucs2[] = L"program"; 

result = 0; 

result = UniStrcmp (ucsl , ucs2); 
if ( result == 0 ) 

printf("The strings are identical\n" ) ; 

else 

printf("The strings are not identical\n" ) ; 
return (ULS SUCCESS) ; 


int 
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UniStrcmpi 

UniStrcmpi compares strings without sensitivity to case. 

Format 


((include <unidef.h> 


int UniStrcmpi 

(const LocaleObject localeobject, const UniChar *ucsl, const UniChar *ucs2) 


Parameters 

locale object (const LocaleObject) 

A valid locale object created by a call to UniCreateLocaleObject or NULL 
ucsl (const UniChar *) 

A null terminated UniChar string to be compared. 
ucs2 (const UniChar *) 

A null terminated UniChar string to be compared. 

Returns 

return value (int) - returns 
less than 0 

ucsl less than ucs2 

0 

ucsl equivalent to ucs2 
Greater than 0 

ucsl greater than ucs 

Remarks 

UniStrcmpi compares ucsl and ucs2 without sensitivity to case. All characters are converted to lowercase 
before the comparison. The locale object is used to convert the characters to lowercase. The locale may be 
specified as NULL to indicate default Unicode casing. 

Related Functions 

• UniStrcmp 

• UniStrncmp 

• UniStmcmpi 

Example 


This example shows how to compare Unicode strings without sensitivity to case, 
((include <stdio.h> 
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((include <unidef.h> 
int main (void) { 

LocaleObject locale_object = NULL; 

UniChar ucsl[] = L"computer"; 

UniChar ucs2[] = L"COMPUTER"; 

int result = 0; 

int rc = ULS_SUCCESS ; 

/iciciciciciciciciciciciciciciciciciciciciciciciciciciciricicicicicicic-k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k J 

/* Assumes LANG environment variable set to a valid locale name, */ 
/* such as fr_FR */ 

l-k-k'k-k-k-k'k-k-k-k-k'k'k'k'k-k-k-k-k-k'k'k'k-k-k-k'k-k'k'k-k'k'k'k'k-k-k-k-k-k-k-k-k-k'k'k'k'k'k'k'k-k'k-k-k'k-k-k'k-k-k-k'k'k'k J 

rc = UniCreateLocaleObject (UNI_UCS_STRING_POINTER, 

(UniChar *)L"", &locale_object) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniCreateLocaleObj ect error: return code = %u\n", rc) ; 
return 1; 

} 

result = UniStrcmpi (locale_object, ucsl, ucs2); 
if ( result == 0 ) 

printf ("The strings are identical\n" ) ; 

else 

printf ("The strings are not identical\n" ) ; 
return (ULS_SUCCESS) ; 

} 


UniStrcoll 


UniStrcoll compares language collation strings. 

Format 


((include <unidef.h> 

int UniStrcoll 

(const LocaleObject localeobject, const UniChar *ucsl, const UniChar *ucs2) 


Parameters 

locale object (const LocaleObject) 

A locale object created by UniCreateLocaleObject or NULL. 


ucsl (const UniChar *) 

A string to be compared. 


ucs2 (const UniChar *) 

A string to be compared. 

Returns 
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return value (int) - returns 

UniStrcoll returns an integer greater than, equal to, or less than zero. The integer returned depends on 
whether: 

• The string pointed to by ucsl is greater than, equal to, or less than the character string pointed to by 
ucs2 

• Both character strings are interpreted as appropriate to the LCCOLLATE category of the locale 
indicated by the locale-object-handle argument, localeobject. The locale may be specified as NULL to 
indicate default Unicode collation. 

Remarks 

UniStrcoll compares the string pointed to by ucsl to the string pointed to by ucs2, both interpreted as 
appropriate to the LC COLLATE category of the locale indicated by the locale object handle argument, 
localeobject. 

Example 


This example shows how to compare Unicode strings using the collating 
sequence specified by the locale object. 

#include <stdio.h> 

#include <unidef.h> 
int main (void) { 

Localeobject locale_object = NULL; 

UniChar ucsl[] = L"axe"; 

UniChar ucs2[] = L"ant"; 

int result = 0; 

int rc = ULS_SUCCESS ; 

/iciciciciciciciciciciciciciciciciciciciciciciciciciciciricicicicicicic-k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k J 

/* Assumes LANG environment variable set to a valid locale name, */ 
/* such as fr_FR */ 

l-k'k'k-k-k-k'k-k-k-k-k'k'k'k'k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k'k'k'k'k-k-k'k'k-k-k-k-k-k'k'k'k'k'k'k'k-k-k'k-k'k-k'k-k-k-k-k-k'k'k J 

rc = UniCreateLocaleObject (UNI_UCS_STRING_POINTER, 

(UniChar *)L"", &locale_object) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniCreateLocaleObj ect error: return code = %u\n", rc) ; 
return 1; 

} 


result = UniStrcoll(locale_object, ucsl, ucs2); 

if ( result == 0 ) 

printf ("The strings are identical\n" ) ; 
else if ( result < 0 ) 

printf ( "Stringl is less than String2\n"); 

else 

printf ( "Stringl is greater than String2\n"); 
return (ULS SUCCESS) ; 


} 


UniStrcpy 
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UniStrcpy copies code element string. 

Format 


((include <unidef.h> 


UniChar * UniStrcpy 

(UniChar *ucsl, const UniChar *ucs2) 


Parameters 

ucsl (UniChar *) 
Target string. 


ucs2 (const UniChar *) 

Source string. 

Returns 

return value (UniChar *) - returns 
UniStrcpy returns ucs 1 . 

Remarks 


UniStrcpy copies the code element string pointed to by ucs2 (including the terminating null code element) 
into the code element array pointed to by ucsl. If copying takes place between objects that overlap, the results 
are unpredictable. Related Functions 

• UniStmcpy 

Example 


This example shows how to copy Unicode strings, 
((include <stdio.h> 

((include <unidef.h> 
int main (void) { 

UniChar ucsl[] = L"computer"; 

UniChar ucs2[10]; 

UniChar *puni; 

puni = UniStrcpy (ucs2 , ucsl); 

} 


UniStrcspn 

UniStrcspn searches for code element string. 
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Format 


((include <unidef.h> 


sizet UniStrcspn 

(const UniChar *ucsl, const UniChar *ucs2) 


Parameters 

ucsl (const UniChar *) 

String to be searched. 

ucs2 (const UniChar *) 

String to search for. 

Returns 

return value (size t) - returns 

UniStrcspn returns the length of the segment. 

Remarks 

UniStrcspn computes the length of the maximum initial segment of the code element string, pointed to by 
ucsl, which consists entirely of code elements not from the string pointed to by ucs2. 

Related Functions 

• UniStrspn 

Example 


This example shows how to search Unicode strings, 
((include <stdio.h> 

((include <unidef.h> 
int main (void) { 

UniChar ucsl[] = L"This is the source string"; 

UniChar ucs2[] = L"source"; 

size_t result; 

result = UniStrcspn (ucsl , ucs2); 
return (ULS_SUCCESS) ; 

} 


UniStrfmon 


UniStrfmon converts monetary value to string. 

Format 
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((include <unidef.h> 

int UniStrfmon 

(const LocaleObject localeobject, UniChar *ucs, size t maxsize, const UniChar *format, ...) 


Parameters 

locale object (const LocaleObject) 

A locale object created by UniCreateLocaleObject or NULL. 


ucs (UniChar *) 
Target string. 


maxsize (size_t) 

Maximum number of code elements to be placed in the target string, 
format (const UniChar *) 

Format to be used when formulating the target string. 


... () 

Zero or more arguments fetched according to the fonnat string. 

Returns 

return value (int) - returns 

If the total number of code elements, including the null terminating code element, is not more than 
maxsize, UniStrfmon returns the number of code elements placed into the array pointed to by ucs, not 
including the null tenninating code element. 

Remarks 

The locale may be specified as NULL to indicate C locale. 

UniStrfmon places characters into the array pointed to by ucs as controlled by the string pointed to by fonnat. 
No more than maxsize code elements are placed into the array. The character string format contains two types 
of objects: plain characters, which are copied to the output stream, and directives, each of which results in the 
fetching of zero or more converted and fonnatted arguments. The results are unpredictable if there are 
insufficient arguments for the fonnat. If the fonnat is exhausted while arguments remain, the excess 
arguments are ignored. A directive consists of a % character, optional conversion specifications, and a 
terminating character that detennines the directive's behavior. 

UniStrfmon converts numeric values to monetary strings, according to the specifications in the format 
parameter. This parameter also contains numeric values to be converted. Characters are placed into this ucs 
array, as controlled by the format parameter. The LCMONETARY category governs the format of the 
conversion. 

UniStrfmon can be called multiple times by including additional format structures, as specified by the format 
parameter. 
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The format parameter specifies a character string that can contain plain characters and conversion 
specifications. Plain characters are copied to the output stream. Conversion specifications result in the 
fetching of zero or more arguments, which are converted and formatted. 

If there are insufficient arguments for the format parameter, the results are undefined. If arguments remain 
after the format parameter is exhausted, the excess arguments are ignored. 

A conversion specification sequence consists of a % (percent) sign, optional flags, optional field width, 
optional left precision, optional right precision, and a required conversion character that determine the 
conversion to be perfonned. 

One or more of the following flags can be specified to control the conversion: 

=f 

An = (equals sign) followed by a single character / that specifies the numeric fill character. The default 
numeric fill character is the space character. This flag does not affect field width filling, which always 
uses the space character. This flag is ignored unless a left precision is specified. The fill character must 
be representable in a single byte in order to work with precision and width counts. 

A 

Do not format the currency amount with grouping characters. The default is to insert grouping 
characters if they are defined for the current locale. 

+or( 

Detennines the representation of positive and negative currency amounts. Only one of these flags may 
be specified. The locale's equivalent of + and - are used if + is specified. The locale's equivalent of 
enclosing negative amounts within parentheses is used if ( is specified. If neither flag is included, the + 
style is used. 

j 

Suppresses the currency symbol from the output conversion. 

Specifies the alignment. If this flag is present, all fields are left-justified (padded to the right) rather 
than right-justified. 

FIELD WIDTH 

w 

The decimal-digit string, w, specifies the minimum field width in which the result of the conversion is 
right-justified (or left-justified if the - flag is specified). The default is zero. 

LEFT PRECISION 

#n 

A # (pound sign) followed by a decimal-digit string, n, specifies the maximum number of digits to be 
formatted to the left of the radix character. This option can be specified to keep formatted output from 
multiple calls to UniStrfmon aligned in the same columns. It can also be used to fill unused positions 
with a special character (for example, $***123.45). This option causes an amount to be formatted as if 
it has the number of digits specified by the n variable. If more than n digit positions are required, this 
option is ignored. Digit positions in excess of those required are filled with the numeric fill character set 
with the =f flag. 

If defined for the current locale and not suppressed with the A flag, grouping separators are inserted 
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before the fill characters (if any) are added. Grouping separators are not applied to fill characters even if 
the fill character is a digit. 

RIGHT PRECISION 


•P 

A .(period) followed by a decimal-digit string, p, specifies the number of digits after the radix character. 
If the value of the p variable is 0, no radix character is used. If a right precision is not specified, a 
default specified by the current locale is used. The amount being formatted is rounded to the specified 
number of digits prior to fonnatting. 

CONVERSION CHARACTERS 


The double argument is formatted according to the current locale's international currency format; 
for example, in the U.S.: USD 1,234.56. 

n 

The double argument is formatted according to the current locale's national currency format; for 
example, in theU.S.: $1,234.56. 

% 

Convert to a %; no argument is converted. The entire conversion specification must be %%. 

Related Functions 

• UniStrftime 

Example 


This example shows how to convert a monetary value to a Unicode string using 
the specified locale object. 

#include <stdio.h> 

#include <unidef.h> 
int main (void) { 

LocaleObject locale_object = NULL; 

UniChar ucs [20]; 

int max_size = 20; 

int elements; 

int rc = ULS_SUCCESS ; 

/-k'k'k-k-k-k-k-k'k-k-k-k'k'k'k-k-k-k-k'k-k-k'k'k-k-k-k-k-k-k-k'k'k'k'k-k-k-k-k'k-k'k'k-k-k-k-k'k'k-k-k-k-k-k-k'k-k-k-k-k-k-k'k'k'k J 

/* Assumes LANG environment variable set to a valid locale name, */ 
/* such as fr_FR */ 

Jiciciciciciciciciciciciciciciriciciciciciciciciciciciciririciricicic-k'k'k'k'k-k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k J 

rc = UniCreateLocaleObject (UNI_UCS_STRING_PO INTER, 

(UniChar *)L"", &locale_object) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniCreateLocaleObj ect error: return code = %u\n", rc) ; 
return 1; 

} 

/* elements contains number of code elements placed into ucs */ 
elements = UniStrfmon (locale_object, ucs, 

max_size, (UniChar *)L"%n", 123.45); 

return (ULS_SUCCESS) ; 

} 


90 of 154 


Unicode Functions (OS/2 Warp) 


UniStrftime 


UniStrftime formats date and time. 

Format 


((include <unidef.h> 
((include <time.h> 


sizet UniStrftime 

(const localeObject localeobject, UniChar *ucs, size t maxsize, const UniChar *format, const 
struct tm *timeptr) 


Parameters 

locale object (const localeObject) 

A locale object created by UniCreateLocaleObject 


ucs (UniChar *) 
Target string. 


maxsize (size t) 

Maximum number of characters to be placed in ucs. 


format (const UniChar *) 

Format of the target string. 


timeptr (const struct tm *) 

Structure containing time and date information. 

Returns 


return value (size t) - returns 

If the total number of resulting code elements, including the null code element, is not more than 
maxsize, the number of code elements placed into the memory location addressed by ucs (not including 
the null code element) is returned. Otherwise, zero is returned and the contents of the memory location 
are indeterminate. 


Remarks 

Convert the internal time and date specification into a character string and place the results in the area pointed 
to by ucs under the direction of format. The null-terminated result of, at most, maxsize code elements, is 
placed in the memory location addressed by ucs. The format string may contain conversion specification 
characters and characters that are placed unchanged into the array. The characters that are converted are 
determined by the LC TIME category of the locale indicated by the locale object handle argument 
locale object and by the values in the time structure pointed to by timeptr. The results are unpredictable when 
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objects being copied overlap. 

The format parameter is a character string containing two types of objects: plain characters that are simply 
placed in the output string and conversion specifications that convert information from the timeptr parameter 
into readable form in the output string. 

A % (percent sign) introduces a conversion specification. 

The type of conversion is specified by one or two conversion characters. The characters and their 
meanings are: 

%a 

Represents the locale's abbreviated weekday name (for example, Sun). 

%A 

Represents the locale's full weekday name (for example, Sunday). 

%b 

Represents the locale's abbreviated month name (for example, Jan). 

%B 

Represents the locale's full month name (for example, January). 

%c 

Represents the locale's date and time format. 

%C 

Represents the century as a decimal number (00-99). 

%d 

Represents the day of the month as a decimal number (01 to 3 1). 

%D 

Represents the date in %m/%d/%y format (for example, 01/31/94). 

%e 

Represents the day of the month as a decimal number ( 1 to 31). A single digit is preceded by a 
space character. 

%h 

Same as %b. 

%H 

Represents the 24-hour-clock hour as a decimal number (00 to 23). 

%I 

Represents the 12-hour-clock hour as a decimal number (01 to 12). 

%j 

Represents the day of the year as a decimal number (001 to 366). 

%m 

Represents the month of the year as a decimal number (01 to 12). 

%M 

Represents the minute of the hour as a decimal number (00 to 59). 

%n 

Specifies a new-line character. 

%p 

Represents the locale's AM or PM string. 

%r 

Represents the time with AM/PM notation (%I:%M:%S%p). 

%R 
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Represents 24-hour-clock time in the format %H:%M. 

%S 

Represents the second of the minute as a decimal number (00 to 61). 

%t 

Specifies a tab character. 

%T 

Represents the time in the format %H:%M:%S. 

%u 

Represents the day of the week as a decimal number (1 to 7). 1 represents Monday. 

%U 

Represents the week of the year as a decimal number (00 to 53). Sunday is considered the first 
day of the week. 

%V 

Represents the week of the year as a decimal number (01 to 53). Monday is considered the first 
day of the week. If the week containing 1 January has four or more days in the new year, then it is 
considered week 1; otherwise, it is week 53 of the previous year, and the next week is week 1. 

%w 

Represents the day of the week as a decimal number (0 to 6). 0 represents Sunday. 

%W 

Represents the week of the year as a decimal number (00 to 53). Monday is considered the first 
day of the week. All days in a new year preceding the first Sunday are considered to be week 0. 

%x 

Represents the locale's date format. 

%X 

Represents the locale's time fonnat. 

%y 

Represents the year of the century (00 to 99). 

%Y 

Represents the year with century as a decimal number for example (1994). 

%Z 

Represents the time-zone name or abbreviation if one can be determined (for example EST). 
Replaced by no bytes if time zone infonnation does not exist. 

%% 

Specifies a % (percent) sign. 

Some conversion specifiers can be modified by the E or O modifier characters to indicate that an alternative 
format or specification should be used rather than the one normally used by the unmodified conversion 
specifier. If the alternative format or specification does not exist for the current locale, the behavior will be as 
if the unmodified conversion specification were used. 

%Ec 

Locale's alternative appropriate date and time representation. 

%EC 

is the name of the base year (period) in the locale's alternative representation. 

%Ex 

is the locale's alternative date representation. 

%EX 

is the locale's alternative time representation. 
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%Ey 

is the offset from %EC (year only) in the locale's alternative representation. 

%EY 

is the full alternative year representation. 

%Od 

is the day of the month using the locale's alternative numeric symbols; filled as needed with 
leading zeros if there is any alternative symbol for zero, otherwise with leading spaces. 

%Oe 

is replaced by the day of the month, using the locale's alternative numeric symbols, filled as 
needed with leading spaces. 

%OH 

is the hour (24-hour clock) using the locale's alternative numeric symbols. 

%OI 

is the hour (12-hour clock) using the locale's alternative numeric symbols. 

%Om 

is the month using the locale's alternative numeric symbols. 

%OM 

is the minutes using the locale's alternative numeric symbols. 

%OS 

is the seconds using the locale's alternative numeric symbols. 

%Ou 

is the weekday of the year (Monday =1) using the locale's alternative numeric symbols. 

%OU 

is the week number of the year (Sunday as the first day of the week) using the locale's alternative 
numeric symbols. 

%OV 

is replaced by the week number of the year (Sunday as the first day of the week) using the 
locale's alternative numeric symbols. 

%Ow 

is the number of the weekday (Sunday=0) using the locale's alternative numeric symbols. 

%OW 

is the week number of the year (Monday as the first day of the week) using the locale's alternative 
numeric symbols. 

%Oy 

is the year (offset from %C) in the locale's alternative representation and using the locale's 
alternative numeric symbols. 

Related Functions 

• UniStrfmon 

• UniStrptime 

Example 


This example shows how to convert a date and time to a Unicode string using 
the specified locale object. 

#include <stdio.h> 

#include <time.h> 
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((include <unidef.h> 
int main (void) { 

LocaleObject locale_object = NULL; 

struct tm Uptime; 

time_t time_date; 

UniChar ucs [30]; 

int max_size = 30; 

int elements; 

int rc = ULS_SUCCESS ; 

/-k'k-k-k'k'k-k-k-k-k-k-k-k'k'k'k'k'k'k'k-k-k'k-k-k-k-k-k-k-k-k'k'k'k'k-k-k-k-k-k-k-k-k-k'k'k-k'k-k-k-k-k-k'k'k'k-k-k-k-k-k'k-k'k'k J 

/* Assumes LANG environment variable set to a valid locale name, */ 
/* such as fr_FR */ 

/iciciciciciciciciciciciririciriciciciciciciciciciciciciciciriricicic-k'k'k'k'k'k'k'k-k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k J 

rc = UniCreateLocaleObject (UNI_UCS_STRING_PO INTER, 

(UniChar *)L"", &locale_object) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniCreateLocaleObj ect error: return code = %u\n", rc) ; 
return 1; 

} 

time_date = time (NULL) ; 
ptime = localtime ( &time_date ) ; 

/* elements contains number of code elements placed into ucs */ 
elements = UniStrftime (locale_object, ucs, 

max_size, (UniChar *)L"%a %b %d\n %I:%M %p", 
ptime) ; 

return (ULS SUCCESS) ; 


} 


UniStrlen 


UniStrlen determines code element count. 

Format 


((include <unidef.h> 

sizet UniStrlen 

(const UniChar *ucs) 


Parameters 

ucs (const UniChar *) 

A null-terminated string composed of UniChar code elements. 

Returns 

return value (size t) - returns 

UniStrlen returns the number of code elements that precede the terminating null code element. 

Remarks 
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UniStrlen computes the length of the code element string pointed to by ucs. 

Example 


This example shows how to determine the code element count of a Unicode string, 
((include <stdio.h> 

((include <unidef.h> 
int main (void) { 
int elements; 

/* elements contains number of code elements in the Unicode string */ 
elements = UniStrlen ( (UniChar * ) L"program" ) ; 
return (ULS SUCCESS) ; 


UniStrlwr 


UniStrlwr converts a Unicode string to lowercase according to the language neutral case mapping tables. 

Format 


((include <unidef.h> 

UniChar *UniStrlwr 

(UniChar *ucsUniStringIn) 


Parameters 

ucsUniStringln (UniChar *) - input 

Unicode string to be mapped to lowercase. 

Returns 

ucsUniStringOut (UniChar *) - returns 
Converted lowercase string. 

Remarks 

The input string must be null-terminated. 

Related Functions 

• UniStrupr 

• UniTolower 

• UniToupper 

Example 


This example shows how to convert a Unicode string to lowercase. 
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((include <stdio.h> 

((include <unidef.h> 
int main (void) { 

UniChar *plwr_unistr ; 

/* plwr_unistr points to the converted lowercase Unicode string */ 
plwr_unistr = UniStrlwr ( (UniChar *)L"IBM"); 
return (ULS_SUCCESS) ; 

} 


UniStrncat 


UniStrncat concatenates a specific number of code elements. 

Format 


((include <unidef.h> 

UniChar * UniStrncat 

(UniChar *ucsl, const UniChar *ucs2, sizet n) 


Parameters 

ucsl (UniChar *) 

String to be appended to. 

ucs2 (const UniChar *) 

String to concatenate. 


n (size t) 

Number of elements in ucs2 to concatenate. 

Returns 

return value (UniChar *) - returns 
Concatenated string. 

Remarks 

UniStrncat appends not more than n code elements (a null code element and code elements that follow it are 
not appended) from the code element array pointed to by ucs2 to the end of the code element string pointed to 
by ucsl. The initial code element of ucs2 overwrites the null code element at the end of ucsl. A terminating 
null code element is always appended to the result. If copying takes place between objects that overlap, the 
results are unpredictable. 

Related Functions 

• UniStrcat 
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Example 


This example shows how to concatenate a specific number of code 
elements onto a Unicode string. 

((include <stdio.h> 

((include <unidef.h> 
int main (void) { 

UniChar ucsl[40] = L"computer"; 

size_t num_elems = 3; 

UniStrncat (ucsl , (UniChar *)L" program", num_elems); 
return (ULS_SUCCESS) ; 

} 


UniStrncmp 

UniStrncmp compares a specific number of code elements. 

Format 


((include <unidef.h> 


int UniStrncmp 

(const UniChar *ucsl, const UniChar *ucs2, sizet n) 


Parameters 

ucsl (const UniChar *) 

String to compare. 

ucs2 (const UniChar *) 

String to compare. 

n (size t) 

Number of code elements to compare. 

Returns 

return value (int) - returns 

UniStrncmp returns an integer greater than, equal to, or less than zero. The integer returned depends on 
whether the possibly null-terminated code element array pointed to by ucsl is greater than, equal to, or 
less than the possibly null-terminated code element array pointed to by ucs2. 

Remarks 

UniStrncmp compares not more than n code elements (code elements that follow a NULL code element are 
not compared) from the code element array pointed to by ucsl to the code element array pointed to by ucs2. 
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Related Functions 

• UniStrcmp 

• UniStrcmpi 

• UniStmcmpi 


Example 


This example shows how to compare a specific number of code 
elements . 

((include <stdio.h> 

((include <unidef.h> 
int main (void) { 

UniChar ucsl[] = L"computer"; 

UniChar ucs2[] = L"computer program"; 

size_t num_elems = 3; 

int result = 0; 

result = UniStrncmp (ucsl , ucs2, num_elems); 
if ( result == 0 ) 

printf("The strings are identical\n" ) ; 

else 

printffThe strings are not identical\n" ) ; 
return (ULS_SUCCESS) ; 

} 


UniStrncmpi 

UniStmcmpi compares one or more code elements of strings without sensitivity to case. 

Format 


((include <unidef.h> 


int UniStrncmpi 

(const LocaleObject localeobject, const UniChar *ucsl, const UniChar *ucs2, const size t n) 


Parameters 

locale object (const LocaleObject) 

A valid locale object created by a call to UniCreateLocaleObject or NULL, 
ucsl (const UniChar *) 

A null-terminated UniChar string to be compared. 
ucs2 (const UniChar *) 

A null terminated UniChar string to be compared. 
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n (const size t) 

The maximum number of code elements to compare. 

Returns 

return value (int) - returns 
less than 0 

ucsl less than ucs2 

0 

ucsl equivalent to ucs2 
Greater than 0 

ucsl greater than ucs 

Remarks 

UniStrncmpi compares ucsl and ucs2 without sensitivity to case. All n code elements are converted to 
lowercase before the comparison. The locale object is used to convert the characters to lowercase. A 
maximum of n code elements are compared. The locale may be specified as NULL to indicate Unicode 
casing. 

Related Functions 

• UniStrcmp 

• UniStrcmpi 

• UniStrncmp 

Example 


This example shows how to compare a specific number of code 
elements without sensitivity to case. 

((include <stdio.h> 


((include <unidef.h> 
int main (void) { 

LocaleObject locale_object; 

UniChar ucsl[] = L"COMPUTER"; 

UniChar ucs2[] = L"computer program"; 

size_t num_elems = 3; 

int result = 0; 

int rc; 

/iciciciciciciciciciciciciciciriciciciciciciciciciciciciciririricicicic-k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k J 


/* Assumes LANG environment variable set to a valid locale name, */ 
/* such as fr_FR */ 

/ititititit-k-k-k-k-k-k'k'k'k'k'k'k'k'k-k-k-k-k-k-k-k-k-k'k'k'k'k-k-k-k-k-k-k-k-k-k-k-k'k'k'k'k'k-k-k-k-k-k-k-k-k-k-k-k-k'k'k'k'k-k j 


rc = UniCreateLocaleObject (UNI_UCS_STRING_PO INTER, 

(UniChar *)L"", &locale_object) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniCreateLocaleObj ect error: return code = %u\n", rc) ; 
return 1; 


result = UniStrncmpi (locale_object, ucsl, ucs2, num_elems); 
if ( result == 0 ) 

printf ("The strings are identical\n" ) ; 

else 

printf ("The strings are not identical\n" ) ; 
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return (ULS SUCCESS) ; 


} 


UniStrncpy 

UniStrncpy copies a specific number of code elements. 

Format 


#include <unidef.h> 


UniChar * UniStrncpy 

(UniChar *ucsl, const UniChar *ucs2, sizet n) 


Parameters 

ucsl (UniChar*) 
Target string. 

ucs2 (const UniChar *) 
Source string. 


n (size t) 

Number of elements in ucs2 to copy. 

Returns 

return value (UniChar *) - returns 
UniStrncpy returns ucsl. 

Remarks 

UniStrncpy copies not more than n code elements (code elements that follow a null code element are not 
copied) from the code element array pointed to by ucs2 to the code element array pointed to by ucsl. If 
copying takes place between objects that overlap, the results are unpredictable. If the code element array 
pointed to by ucs2 is a code element string that is shorter than n code elements, null code elements are 
appended to the copy in the code element array pointed to by ucsl, until n code elements, in all, have been 
written. 

Related Functions 

• UniStrcpy 

Example 


This example shows how to copy a specific number of code 
elements in a Unicode string. 
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((include <stdio.h> 

((include <unidef.h> 
int main (void) { 

UniChar ucsl[] = L"computer"; 

UniChar ucs2[10]; 

UniChar *puni; 

size_t num_elems = 4; 

puni = UniStrncpy (ucs2 , ucsl, num_elems); 
return (ULS_SUCCESS) ; 

} 


UniStrpbrk 

UniStrpbrk locates code elements in a code element string. 

Format 


((include <unidef.h> 


UniChar * UniStrpbrk 

(const UniChar *ucsl, const UniChar *ucs2) 


Parameters 

ucsl (const UniChar *) 

String to be searched. 

ucs2 (const UniChar *) 

String to search for. 

Returns 

return value (UniChar *) - returns 

UniStrpbrk returns a pointer to the code element or a null pointer, if the code element from the code 
element string from ucs2, does not occur in ucsl. 

Remarks 

UniStrpbrk locates the first occurrence, in the string pointed to by ucsl, of any code element from the code 
element string pointed to by ucs2. Related Functions 

• UniStrstr 

Example 


This example shows how to locate code elements in a Unicode string. 
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((include <stdio.h> 

((include <unidef.h> 
int main (void) { 

UniChar ucsl[] = L"computer"; 

UniChar ucs2[] = L"put"; 

UniChar *puni; 

puni = UniStrpbrk (ucsl , ucs2); 
if (puni) 

printf("The sub string was foundin''); 
return (ULS_SUCCESS) ; 

} 


UniStrptime 

UniStrptime converts date and time. 

Format 


((include <unidef.h> 
((include <time.h> 


UniChar * UniStrptime 

(const LocaleObject localeobject, const UniChar *buf, const UniChar *fmt, struct tm *tm) 


Parameters 

locale object (const LocaleObject) 

A locale object created by UniCreateLocaleObject. 

buf (const UniChar *) 

String to be converted. 

fmt (const UniChar *) 

Format of the source string. 

tm (struct tm *) 

Time/data structure to receive the time/data information held in the string buf. 

Returns 

return value (UniChar *) - returns 

Returns a pointer to the character following the last character; otherwise, a NULL pointer is returned 
and the contents of the tm structure are undefined. 

Remarks 
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UniStrptime converts the character string pointed to by buf to a time value, which is stored in the structure 
pointed to by tm, using the format specified by fmt. A pointer to the character following the last character in 
the string pointed to by buf is returned. The character string pointed to by fmt consists of field descriptors and 
text characters, similar to the scanf. Each field descriptor consists of a % character followed by another 
character that specifies the replacement for the field descriptor. The type of conversion is specified by one or 
two conversion characters. The characters and their meanings are specified in the Format Strings and 
Modified Directives sections. 

FORMAT STRINGS 

%a 

Day of the week, abbreviated or full name may be specified (for example Sun). 

%A 

Same as %a. 

%b 

Represents the locale's month name, abbreviated or fullname may be specified. 

%B 

Same as %b. 

%c 

Represents the locale's date and time format. 

%C 

Represents the century number (0 to 99). 

%d 

Represents the day of the month as a decimal number (01 to 3 1). 

%D 

Represents the date in %m/%d/%y format (for example, 01/31/91). 

%e 

Same as %d. 

%h 

Same as %b. 

%H 

Represents the 24-hour-clock hour as a decimal number (00 to 23). 

%I 

Represents the 12-hour-clock hour as a decimal number (01 to 12). 

%j 

Represents the day of the year as a decimal number (001 to 366). 

%m 

Represents the month of the year as a decimal number (01 to 12). 

%M 

Represents the minute of the hour as a decimal number (00 to 59). 

%n 

Represents any white space. 

%p 

Represents the locale's AM or PM string. 

%r 

Represents the time as %I:%M:%S%p. 

%R 

Represents the time as %H:%M. 
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%s 

Represents the second of the minute as a decimal number (00 to 61). 

%t 

Represents any white space. 

%T 

Represents time in the fonnat %H:%M:%S. 

%U 

Represents the week of the year as a decimal number (00 to 53). Sunday is considered the first 
day of the week. 

%w 

Represents the day of the week as a decimal number (0 to 6). Sunday is considered as 0. 

%W 

Represents the week of the year as a decimal number (00 to 53). Monday is considered the first 
day of the week. 

%x 

Represents the locale's date format. 

%X 

Represents the locale's time fonnat. 

%y 

Represents the year of the century (00 to 99). 

%Y 

Represents the year with century as a decimal number (for example 1994). 

%% 

Specifies a % (percent) sign. 

MODIFIED DIRECTIVES 

Some directives can be modified by the E and O modifier characters to indicate that an alternative format or 
specification should be used rather than the one normally used by the unmodified directive. If the alternative 
format or specification does not exist in the current locale, the behavior will be as if the unmodified directive 
were used. 

%Ec 

is the locale's alternative appropriate date and time representation. 

%EC 

is the name of the base year (period) in the locale's alternative representation. 

%Ex 

is the locale's alternative date representation. 

%EX 

is the locale's alternative time representation. 

%Ey 

is the offset from %EC (year only) in the locale's alternative representation. 

%EY 

is the full alternative year representation. 

%Od 

is the day of the month using the locale's alternative numeric symbols; leading zeros are 
permitted but not required. 

%Oe 
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is the same as %Od. 

%OH 

is the hour (24-hour clock) using the locale's alternative numeric symbols. 

%OI 

is the hour (12-hour clock) using the locale's alternative numeric symbols. 

%Om 

is the month using the locale's alternative numeric symbols. 

%OM 

is the minutes using the locale's alternative numeric symbols. 

%OS 

is the seconds using the locale's alternative numeric symbols. 

%OU 

is the week number of the year (Sunday as the first day of the week) using the locale's alternative 
numeric symbols. 

%Ow 

is the number of the weekday (Sunday=0) using the locale's alternative numeric symbols. 

%OW 

is the week number of the year (Monday as the first day of the week) using the locale's alternative 
numeric symbols. 

%Oy 

is the year (offset from %C) in the locale's alternative representation and using the locale's 
alternative numeric symbols. 

A format specification consisting of white-space characters is performed by reading input until the first 
nonwhite-space character (which is not read) or no more characters can be read. 

A format specification consisting of an ordinary character is performed by reading the next character 
from the string parameter. If this character differs from the character comprising the directive, the 
directive fails and the differing character and any characters following it remain unread. Case is ignored 
when matching string items, such as month or weekday names. 

Related Functions 

• UniStrftime 

Example 


This example shows how to convert a time date string to a time structure. 
#include <stdio.h> 

#include <time.h> 


#include <unidef.h> 
int main (void) { 

LocaleObject locale_object; 

UniChar uni_fmt[] = L"%A 

UniChar uni_time_str [ ] = 

UniChar *puni; 

struct tm convrt_time; 

int rc; 

rc = UniCreateLocaleObject (UNI_UCS_STRING_POINTER, 

(UniChar *)L"en US", Slocale object) 


%b %d %r %Y" ; 

L"Wednesday Oct 23 03:07:00 PM 1995"; 
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if (rc ! = ULS_SUCCESS ) { 

printf ( "UniCreateLocaleObj ect error: return code = %u\n", rc) ; 
return 1; 

} 

puni = UniStrptime (locale_object, uni time_str, uni_fmt, 
&convrt_time) ; 
if ( puni == NULL ) { 

printf ("UniStrptime error\n") ; 
return ( 1 ) ; 

} 

else 

return (ULS SUCCESS) ; 


} 


UniStrrchr 


UniStrrchr locates last occurrence of code element. 

Format 


((include <unidef.h> 

UniChar * UniStrrchr 

(const UniChar *ucs, UniChar uc) 


Parameters 

ucs (const UniChar *) 

String to be searched. 

uc (UniChar) 

UniChar code element to search for. 

Returns 

return value (UniChar *) - returns 

UniStrrchr returns either a pointer to the found code element or a null pointer, if uc does not occur in 
the code element string. 

Remarks 

UniStrrchr locates the last occurrence of uc in the code element string pointed to by ucs. The terminating null 
code element is considered to be part of the string. 

Related Functions 

• UniStrchr 

Example 
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This example shows how to locate the last occurrence of a code element 
in a Unicode string. 

((include <stdio.h> 

((include <unidef.h> 
int main (void) { 

UniChar ucs[] = L"computer"; 

UniChar uc = L't'; 

UniChar *puni; 

puni = UniStrrchr (ucs , uc) ; 
if (puni) 

printf("The character is contained in the string\n"); 
return (ULS_SUCCESS) ; 

} 


UniStrspn 

UniStrspn determines the number of code elements in a segment. 

Format 


((include <unidef.h> 


sizet UniStrspn 

(const UniChar *ucsl, const UniChar *ucs2) 


Parameters 

ucsl (const UniChar *) 

String to be searched. 

ucs2 (const UniChar *) 

String of code elements to search for. 

Returns 

return value (size t) - returns 

UniStrspn returns the length of the segment. 

Remarks 

UniStrspn computes the length of the maximum initial segment of the code element string pointed to by ucsl, 
which consists entirely of code elements from the code element string pointed to by ucs2. 

Related Functions 

• UniStrcspn 
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Example 


This example shows how to determine the number of elements in a Unicode string, 
((include <stdio.h> 

((include <unidef.h> 
int main (void) { 

UniChar ucsl[] = L"computer"; 

UniChar ucs2[] = L"omc"; 

size_t num_elems = 0; 

num_elems = UniStrspn (ucsl , ucs2); 
if (num_elems) 

printffThe first %d characters were foundin'', num_elems); 
return (ULS_SUCCESS) ; 

} 


UniStrstr 


UniStrstr locates a code element sequence. 

Format 


((include <unidef.h> 

UniChar * UniStrstr 

(const UniChar *ucsl, const UniChar *ucs2) 


Parameters 

ucsl (const UniChar *) 

String to be searched. 
ucs2 (const UniChar *) 

String of code elements to search for. 

Returns 

return value (UniChar *) - returns 

UniStrstr returns either a pointer to the located code element string or a null pointer, if the string is not 
found. 

If ucs2 points to a code element string with zero length, the function returns ucs 1 . 

Remarks 

UniStrstr locates the first occurrence, in the code element string pointed to by ucsl of the sequence of code 
elements (excluding the ending null code element), in the code element string pointed to by ucs2. 
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Related Functions 

• UniStrpbrk 

Example 


This example shows how to locate a code element sequence in a Unicode string, 
((include <stdio.h> 

((include <unidef.h> 
int main (void) { 

UniChar ucsl[] = L"computer"; 

UniChar ucs2[] = L"put"; 

UniChar *puni; 

puni = UniStrstr (ucs 1 , ucs2); 
if (puni) 

printffThe code element sequence was foundin''); 
return (ULS_SUCCESS) ; 

} 


UniStrtod 


UniStrtod converts character string to double-precision floating point. 

Format 


((include <unidef.h> 

int UniStrtod 

(const LocaleObject localeobject, const UniChar *nptr, UniChar **endptr, double *result) 


Parameters 

locale object (const LocaleObject) 

A locale object created by UniCreateObject. 

nptr (const UniChar *) 

String to be converted. 


endptr (UniChar **) 

A pointer to the first UniChar that is not recognized as being part of a number, 
result (double *) 

Resulting double-precision floating-point number. 

Returns 
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return value (int) - returns 

UniStrtod returns one of the following values: 

ULSSUCCESS 

The function was successful. 

ULSBADOBJ 

Invalid locale object specified. 

ULSINVALID 

The endptr or result argument contains an invalid pointer value. The reliable detection of this error is 
implementation dependent. 

ULSRANGE 

The conversion resulted in an out-of-range condition. 

Remarks 

UniStrtod converts the initial portion of the string pointed to by nptr to double-precision floating-point 
representation. First, it decomposes the input string into three parts: 

1. An initial, possibly empty, sequence of white-space characters (as indicated by the space attribute). 

2. A subject sequence resembling a floating-point constant. 

3. A final string of one or more unrecognized characters, including the terminating null character of the 
input string. 

Then, it attempts to convert the subject sequence to a floating-point number, and returns the result in the area 
pointed to by result. A pointer to the final string is stored in the object pointed to by endptr, provided that 
endptr is not a null pointer. 

Related Functions 

• UniStrtol 

• UniStrtok 

• UniStrtoul 

Example 


This example shows how to convert a Unicode string to a double precision 
floating point number. 

((include <stdio.h> 

((include <unidef.h> 
int main (void) { 

LocaleObject locale_object; 

UniChar uni_string[] = L"3 . 1415926This stopped it"; 

UniChar *uni_stop_string; 

double double_num; 

int rc; 

/-k'k'k-k'k'k'k-k-k-k-k-k-k-k'k'k'k'k'k-k-k'k-k'k-k-k-k-k-k-k-k'k'k'k'k-k-k'k-k-k-k-k-k-k'k'k'k'k'k'k'k-k-k-k-k'k-k-k-k-k-k-k-k'k'k j 

/* Assumes LANG environment variable set to a valid locale name, */ 
/* such as fr_FR */ 

Jiciciciciciciciciciciciciriririciciciciciciciciciciciciriciciricicic-k'k'k'k'k-k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k J 

rc = UniCreateLocaleObject (UNI_UCS_STRING_PO INTER, 

(UniChar *)L"", &locale_object) ; 
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if (rc ! = ULS_SUCCESS ) { 

printf ( "UniCreateLocaleObj ect error: return code = %u\n", rc) ; 
return 1; 

} 

rc = UniStrtod (locale_object, uni_string, &uni_stop_string, 
&double_num) ; 
if (rc ! = ULS_SUCCESS ) { 

printf ( "UniStrtod error: return code = %u\n", rc) ; 
return 1; 

} 

else { 

printf ("The double precision number is %f\n", double_num) ; 
return (ULS SUCCESS); 


} 


UniStrtol 


UniStrtol converts a character string to a long integer. 

Format 


((include <unidef.h> 

int UniStrtol 

(const LocaleObject localeobject, const UniChar *nptr, UniChar **endptr, int base, long 
int *result) 


Parameters 

locale object (const LocaleObject) 

A locale object created by UniCreateLocaleObj ect or NULL. 


nptr (const UniChar *) 

String to be converted. 


endptr (UniChar **) 

A pointer to the first UniChar that is not recognized as being part of a number. 


base (int) 

The radix used to perform conversion. 

result (long int *) 

The resulting integer. 

Returns 

return value (int) - returns 
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UniStrtol returns one of the following values: 

ULSSUCCESS 

The function was successful. 

ULSBADOBJ 

Invalid locale object specified. 

ULSINVALID 

The endptr or result argument contains an invalid pointer value. The reliable detection of this error is 
implementation-dependent. 

ULSRANGE 

The conversion resulted in an out-of-range condition. 

Remarks 

The locale may be specified as NULL to indicate C locale. 

UniStrtol converts the initial portion of the string pointed to by nptr to long int representation. First, it 
decomposes the input string into three parts: 

1. An initial, possibly empty, sequence of white-space characters (as indicated by the space attribute). 

2. A subject sequence, resembling an integer, that is represented in the radix and determined by the value 
of base. 

3. A final string of one or more unrecognized characters, including the ending null character of the input 
string. 

Then, it attempts to convert the subject sequence to an unsigned integer, and returns the result in the area 
pointed to by result. A pointer to the final string is stored in the object pointed to by endptr, provided that 
endptr is not a null pointer. 

If the value of base is between 2 and 36, the letters a (or A) to z (or Z), inclusive, are ascribed the values 10 to 
35. Only letters whose ascribed value is less than base are permitted. 

If base is set to 0, the expected fonn of the subject sequence is a decimal, octal, or hexadecimal constant. 
Decimal constants begin with a nonzero digit. Octal constants begin with 0. Hexadecimal constants begin 
with Ox or OX. 

Related Functions 

• UniStrtod 

• UniStrtok 

• UniStrtoul 

Example 


This example shows how to convert a Unicode string to a long integer. 
#include <stdio.h> 

#include <unidef.h> 
int main (void) { 

LocaleObject locale_object; 

UniChar uni_string[] = L"110134932" ; 
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UniChar *uni_stop_string; 

long int long_num; 

int rc; 

/iciciciciciciciciciciciciriciciciciciciciciciciciciciciriririricicicic-k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k J 

/* Assumes LANG environment variable set to a valid locale name, */ 
/* such as fr_FR */ 

j ■ k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k j 

rc = UniCreateLocaleObject (UNI_UCS_STRING_PO INTER, 

(UniChar *)L"", &locale_object) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniCreateLocaleObj ect error: return code = %u\n", rc) ; 
return 1; 

} 

rc = UniStrtol (locale_object, uni_string, &uni_stop_string, 

10, &long_num) ; 
if (rc ! = ULS_SUCCESS ) { 

printf ( "UniStrtol error: return code = %u\n", rc) ; 
return 1; 


else { 

printf ("The long integer is %ld\n", long_num) ; 
return (ULS_SUCCESS) ; 

} 


} 


UniStrtok 

UniStrtok converts a Unicode string to tokens. 

Format 


((include <unidef.h> 

UniChar *UniStrtok 

(UniChar *ucsStringl, const UniChar *ucsString2) 


Parameters 

ucsStringl (UniChar *) - input 

Unicode string containing zero or more tokens. 

ucsStringl is a string of zero or more tokens. The tokens in ucsStringl can be separated by one or more 
of the delimiters in ucsString2. UniStrtok does not support the passing of NULL for ucsStringl 
parameter as is supported in the ANSI C strtok function. 


ucsString2 (const UniChar *) - input 

Set of UniChar characters that can be used as delimiters. 

ucsString2 is the set of characters serving as delimiters of the tokens in ucsStringl. 
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Returns 

ucsToken (UniChar *) - returns 
Pointer to the first token. 

Remarks 

UniStrtok will return the first token in the string specified in ucsStringl. UniStrtok replaces the delimiter 
character with 0x0000 and returns a pointer to the token. 

Related Functions 

• UniStrtod 

• UniStrtol 

• UniStrtoul 

Example 


This example shows how to convert a Unicode string to tokens. 

((include <stdio.h> 

((include <unidef.h> 
int main (void) { 

UniChar *uni_string = L"a string, of, , tokens"; 

UniChar *puni_token; 

int uni lenl; 

int uni_len2; 

int token_count = 0; 

uni lenl = UniStrlen (uni string) ; 

puni_token = UniStrtok (uni_string, (UniChar *)L","); 
++token_count; 

/* Continue to loop through the string looking for tokens */ 
do 
{ 

uni len2 = UniStrlen (puni token) + 1; 

puni token += uni len2; 

if (puni_token < uni_string + uni_lenl) 

{ 

puni^token = UniStrtok (puni_token, (UniChar *)L","); 
++token_count ; 

} 

else 

break; 

} while ( 1 ) ; 

printf("%d tokens were foundin'', token_count ) ; 
return (ULS_SUCCESS) ; 

} 


UniStrtoul 


UniStrtoul converts a character string to an unsigned long integer. 

Format 
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((include <unidef.h> 

int UniStrtoul 

(const LocaleObject localeobject, const UniChar *nptr, UniChar **endptr, int base, unsigned 
long int *result) 


Parameters 

locale object (const LocaleObject) 

A locale object created by UniCreateLocaleObject or NULL. 


nptr (const UniChar *) 

String to be converted. 


endptr (UniChar **) 

A pointer to the first UniChar that is not recognized as being part of a number. 


base (int) 

The radix used to perform conversion. 


result (unsigned long int *) 

The resulting unsigned long integer. 

Returns 

return value (int) - returns 

UniStrtoul returns one of the following values: 

ULSSUCCESS 

The function was successful. 

ULSBADOBJ 

Invalid locale object specified. 

ULS_INVALID 

The endptr or result argument contains an invalid pointer value. The reliable detection of this error is 
implementation dependent. 

ULS_RANGE 

The conversion resulted in an out-of-range condition. 

Related Functions 

• UniStrtod 

• UniStrtol 

• UniStrtok 


Remarks 

The locale may be specified as NULL to indicate C locale. 
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UniStrtoul converts the initial portion of the string pointed to by nptr to unsigned long int representation. 

First, it decomposes the input string into three parts: 

1 . An initial, possibly empty, sequence of white-space characters (as indicated by the space 
attribute). 

2. A subject sequence resembling an unsigned integer represented in some radix determined by the 
value of base. 

3. A final string of one or more unrecognized characters, including the terminating null character of 
the input string. 

Then, it attempts to convert the subject sequence to an unsigned integer, and returns the result in the 
area pointed to by result. A pointer to the final string is stored in the object pointed to by endptr, 
provided that endptr is not a null pointer. 

If the value of base is between 2 and 36, the letters a (or A) to z (or Z) inclusive are ascribed the values 
10 to 35. Only letters whose ascribed value is less than base are permitted. 

If base is set to 0, the expected form of the subject sequence is a decimal, octal or hexadecimal constant. 
Decimal constants begin with a nonzero digit. Octal constants begin with 0. Hexadecimal constants 
begin with Ox or OX. 

Example 

This example shows how to convert a Unicode string to an unsigned long integer. 

((include <stdio.h> 

((include <unidef.h> 
int main (void) { 

LocaleObject locale_object; 

UniChar uni_string[] = L"110134932"; 

UniChar *uni_stop_string; 

unsigned long int long_num; 
int rc; 

/* Assumes LANG environment variable set to a valid locale name, */ 

/* such as fr_FR */ 

/**i?*icicicicici?i?icicicicic*ic*icicicic*-k'k'k-k-k-k-k'k'k'k'k'k'k'k'k'k'k'k'k-k-k'k'k'k'k'k'k'k'k'k'k'k'k'k'k-k-k-k-k'k'k j 

rc = UniCreateLocaleObject (UNI_UCS_STRING_PO INTER, 

(UniChar *)L"", &locale_object) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniCreateLocaleObj ect error: return code = %u\n", rc) ; 
return 1; 

} 

rc = UniStrtoul (locale_object, uni_string, &uni_stop_string, 

10, &long_num) ; 
if (rc ! = ULS_SUCCESS ) { 

printf ( "UniStrtoul error: return code = %u\n", rc) ; 
return 1; 

} 

else { 

printf ("The unsigned long integer is %lu\n", long_num) ; 
return (ULS_SUCCESS) ; 

} 

} 
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UniStrupr 

UniStrupr converts a Unicode string to uppercase according to the language neutral case mapping tables. 

Format 


#include <unidef.h> 


UniChar *UniStrupr 

(UniChar *ucsUniStringIn) 


Parameters 

ucsUniStringln (UniChar *) - input 

Unicode string to be mapped to uppercase. 

Returns 

ucsUniStringOut (UniChar *) - returns 
Converted uppercase string. 

Remarks 

The input string must be null-terminated. 

Related Functions 

• UniStrlwr 

• UniTolower 

• UniToupper 

Example 


This example shows how to uppercase Unicode strings according to the 
language neutral case mapping tables. 

((include <stdio.h> 

((include <unidef.h> 
int main (void) { 

UniChar ucs[] = L"computer"; 

UniChar *puni; 

puni = UniStrupr (ucs ) ; 
return (ULS SUCCESS) ; 


UniStrxfrm 


118 of 154 


Unicode Functions (OS/2 Warp) 


UniStrxfrm transforms a character string into collating weights. 

Format 


((include <unidef.h> 

sizet UniStrxfrm 

(const LocaleObject localeobject, UniChar *ucsl, const UniChar *ucs2, size t n) 


Parameters 

locale object (const LocaleObject) 

A locale object created by UniCreateLocaleObject or NULL. 

ucsl (UniChar *) - output 

Target transformed string. 

ucs2 (const UniChar *) - input 

Source string to be transformed. 

n (size t) - input 

Maximum number of code elements to be placed in ucsl. 

Returns 

return value (size_t) - returns 

UniStrxfrm returns the length of the transformed string (not including the tenninating null code element). If 
the value returned is n or more, the contents of the array pointed to by ucsl are indetenninate. If ucsl is a null 
pointer, UniStrxfrm returns the number of elements required to contain the transformed character string. 

Remarks 

UniStrxfrm transfonns the string pointed to by ucs2 to values that represent character collating weights and 
places the resulting string into the array pointed to by ucsl. The transformation is such that, if UniStrcmp is 
applied to two transformed strings, it returns a value greater than, equal to, or less than 0, corresponding to the 
result of UniStrcoll applied to the same two original strings. No more than n elements are placed into the 
resulting array pointed to by ucsl, including the terminating null code element. If n is zero, ucsl is permitted 
to be a null pointer. If copying takes place between objects that overlap, the results are unpredictable. 

UniStrxfrm is controlled by the LC COLLATE category of the locale as indicated by the locale object handle 
argument, locale object. The locale may be specified as NULL to indicate Unicode collation. 

Example 


This example shows how to collect character collating weights from Unicode 
strings using the specified locale object. 

((include <stdio.h> 


119 of 154 



Unicode Functions (OS/2 Warp) 


((include 

<unidef . h> 

int main (void) { 

LocaleObject locale object = NULL; 

UniChar 

*pucsl ; 

UniChar 

*pucs2 = L"computer"; 

int 

num elems = 8; 

int 

num elems trx = 0; 

int 

result = 0; 

int 

rc = ULS_SUCCESS ; 

Jiciciciriciciriciciciciriciciricicicicicicicicicicicicicicicicicicicic-k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k J 

/* Assumes LANG environment variable set to a valid locale name, */ 
/* such as fr FR */ 

I'k'k'k-k'k'k'k-k-k-k'k-k'k'k'k'k'k'k'k-k'k'k-k'k-k-k'k-k-k-k-k'k'k'k'k-k-k'k-k'k'k'k'k-k-k'k-k'k-k'k'k-k'k-k-k-k'k-k-k'k-k-k-k'k'k j 


rc = UniCreateLocaleObject (UNI_UCS_STRING_PO INTER, 

(UniChar *)L"", &locale_object) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniCreateLocaleObj ect error: return code = %u\n", rc) ; 
return 1; 

} 

/* Calculate the space needed for the collating weights */ 

liciciciciciciciciciciciciciciciciciciciciciciciciciciciricicicicicicicicicicicicicic'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k I 

num_elems = UniStrxfrm (locale_object, NULL, pucs2, 0); 

pucsl = (UniChar *) malloc((num_elems + 1) * sizeof(UniChar)); 

if ( ! pucs 1 ) 
return 1; 

liciciciciciciciciciciciciciciciciciciciriciciciciciciciricicicicicicicicicicicicicic'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k J 

/* Obtain the collating weights for the Unicode string. */ 

/* num_elems_trx should be less than num_elems */ 

Ji<j<j<jtitititj<j<-k-k'k'k'k'k-k-k-k-k-k-k-k'k-k-k-k-k-k-k'k'k-k-k-k-k-k'k'k-k'k-k-k-k-k-k'k'k-k-k-k-k-k-k'k'k'k-k-k-k-k'k-k-k'k'k'k'k-k J 

num_elems_trx = UniStrxfrm ( locale_object, pucsl, 

pucs2, num_elems + 1); 
if (num_elems_trx >= (num_elems +1)) { 

printf ( "UniStrxfrm error : \n" ) ; 
return 1; 


return (ULS SUCCESS) ; 


} 


UniTolower 


UniTolower converts a Unicode character to lowercase according to the language neutral case mapping tables. 

Format 


((include <unidef.h> 

UniChar UniTolower 

(UniChar ucUniCharln) 


Parameters 
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ucUniCharln (UniChar) - input 

Unicode character to be mapped to lowercase. 

Returns 

ucUniCharOut (UniChar) - returns 
Converted lowercase character. 

Related Functions 

• UniStrlwr 

• UniStrupr 

• UniToupper 

Example 


This example shows how to convert a Unicode character to lowercase according to the 
language neutral case mapping tables. 

((include <stdio.h> 

((include <unidef.h> 
int main (void) { 

UniChar uni_upr = L'C'; 

UniChar uni^lwr; 

uni lwr = UniTolower (uni upr) ; 
return (ULS_SUCCESS) ; 

} 


UniToupper 

UniToupper converts a Unicode character to uppercase according to the language neutral case mapping tables. 

Format 


((include <unidef.h> 


UniChar UniToupper 

(UniChar ucUniCharln) 


Parameters 

ucUniCharln (UniChar) - input 

Unicode character to be mapped to uppercase. 

Returns 

ucUniCharOut (UniChar) - returns 
Converted uppercase character. 
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Related Functions 

• UniStrlwr 

• UniStrupr 

• UniTolower 

Example 


This example shows how to convert a Unicode character to uppercase according to the 
language neutral case mapping tables. 

((include <stdio.h> 

((include <unidef.h> 
int main (void) { 

UniChar uni^lwr = L'c'; 

UniChar uni_upr; 

uni upr = UniToupper (uni lwr) ; 
return (ULS_SUCCESS) ; 

} 


UniTransformStr 


UniTransformStr transforms strings according to a XfonnObject created by UniCreateTransformObject. 

Format 


((include <unidef.h> 

int UniTransformStr 

(XformObject xformobject, const UniChar *InpBuf, int *InpSize, UniChar *OutBuf, 
int *OutSize) 


Parameters 

xform object (XformObject) 

An xform_object created by UniCreateTransformObject. 


InpBuf (const UniChar *) 

String to be transformed. 


InpSize (int *) 

Number of code elements in InpBuf. 


OutBuf (UniChar *) 
Target string. 


OutSize (int *) 
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Number of code elements that OutBuf can hold. 

Returns 

return value (int) - returns 
UniTransformStr returns one of the following: 

ULSSUCCESS 

Transformation completed without errors. 

ULSUNSUPPORTED 

The transfonn object was not found. 

Remarks 

UniTransformStr transforms a UniChar character string as specified by the transformation object handle 
xformobject for the LCCTYPE category. This category applies to the locale object that was used to create 
the transformation handle xform object (by UniCreateTransformObject). The text from the input buffer is 
transfonned and the result is placed in the output buffer. Any characters not included in the transformation 
type referenced by xform object are moved, to the output buffer, unchanged. 

The InpSize argument, on input, specifies the number of code elements to be transformed. A value of -1 
indicates that the input is delimited by a UniChar NULL character (0x0000). On return, the value is modified 
to the actual number of code elements processed in the source string. 

The OutSize argument, on input, specifies the size of the output buffer (number of code elements). On return, 
the value is modified to the actual number of code elements placed in OutBuf. 

Related Functions 

• UniCreateTransformObject 

• UniFreeTransformObject 

Example 


This example shows how to create and use a transform object. 
#include <stdio.h> 


#include <unidef.h> 
int main (void) { 

LocaleObject locale_object = NULL; 


XformObject 

int 

int 

int 

UniChar 

UniChar 

/* * 


xform_object = NULL; 
rc = ULS_SUCCESS ; 
in_unistr_elem = 0; 
out_unistr_elem = 10; 

*pin_unistr = (UniChar *)L"os2"; 
out_unistr [10] ; 

iciciriciciricicicicicicicicicicicicicicicicicic'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k 


*/ 


/* Assumes LANG environment variable set to a valid locale name, */ 
/* such as fr_FR */ 

/•k'k'k-k'k-k'k-k-k-k-k'k'k'k'k-k-k-k-k-k-k-k'k-k-k-k-k-k-k'k-k'k'k'k'k-k-k-k-k'k-k'k'k-k'k'k'k'k-k-k'k-k-k-k-k'k-k-k-k-k'k-k'k'k'k J 


rc = UniCreateLocaleObject (UNI_UCS_STRING_PO INTER, 

(UniChar *)L"", &locale_object) ; 
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if (rc ! = ULS_SUCCESS ) { 

printf ( "UniCreateLocaleObj ect error: return code = %u\n", rc) ; 
return 1; 

} 

/* Create an upper case transform object */ 
rc = UniCreateTransf ormObject (locale_object, 

(UniChar *)L"upper", &xform_object) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ("UniCreateTransformObject error: return code = %u\n", rc) ; 
return 1; 

} 

/* Calculate the number of elements to transform */ 
in_unistr_elem = UniStrlen (pin_unistr) + 1; 

/* Make call to transform input string to uppercase */ 
rc = UniTransf ormStr (xform_object, pin_unistr, 

&in_unistr_elem, out_unistr, 

&out_unistr_elem) ; 
if (rc ! = ULS_SUCCESS ) { 

printf ( "UniTransf ormStr error: return code = %u\n", rc) ; 
return 1; 

} 

return ULS SUCCESS; 


} 


UniTransLower 


UniTransLower converts a Unicode character to lowercase using the specified locale. 

Format 


((include <unidef.h> 

UniChar UniTransLower 

(const LocaleObject localeobject, UniChar uc) 


Parameters 

locale object (const LocaleObject) 

A locale object created by UniCreateLocaleObj ect or NULL. 


uc (UniChar) 

The character to be transformed. 


Returns 

return value (UniChar) - returns 

UniTransLower returns the transformed character. The input character is returned if there is no 
transformation defined for the character in locale object. 

Related Functions 
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• UniTransUpper 

Example 


This example shows how to convert a Unicode character to lowercase. 

((include <stdio.h> 

((include <unidef.h> 
int main (void) { 

LocaleObject locale_object; 

UniChar uni_upr = L'C'; 

UniChar uni lwr; 

int rc; 

/*j<j<ititititj(j<-k-k'k'k'k'k-k-k-k'k-k-k-k-k'k-k-k-k-k'k'k'k'k-k'k-k-k'k-k-k'k-k-k-k-k'k'k'k'k'k'k'k-k-k-k-k'k-k-k-k-k'k'k'k'k-k J 

/* Assumes LANG environment variable set to a valid locale name, */ 
/* such as fr_FR */ 

J*j<j<itjt-k'k-k-k-k-k'k'k'k'k-k'k-k'k-k-k'k'k'k-k-k-k'k'k'k'k'k-k'k-k-k-k-k-k-k-k-k-k-k-k-k-k'k'k'k'k-k'k'k'k'k-k-k-k-k'k'k'k'k-k J 

rc = UniCreateLocaleObject (UNI_UCS_STRING_PO INTER, 

(UniChar *)L"", &locale_object) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniCreateLocaleObj ect error: return code = %u\n", rc) ; 
return 1; 

} 

uni lwr = UniTransLower (locale_object, uni_upr) ; 
return (ULS_SUCCESS) ; 

} 


UniTransUpper 

UniTransUpper converts Unicode character to uppercase using the specified locale. 

Format 


((include <unidef.h> 


UniChar UniTransUpper 

(const LocaleObject localeobject, UniChar uc) 


Parameters 

locale object (const LocaleObject) 

A locale object created by UniCreateLocaleObject or NULL 


uc (UniChar) 

The character to be transformed. 


Returns 

return value (UniChar) - returns 

This function returns the transformed character. The input character is returned if there is no 
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transformation defined for the character in localeobject. 

Related Functions 

• UniTransLower 

Example 


This example shows how to convert a Unicode character to uppercase. 

((include <stdio.h> 

((include <unidef.h> 
int main (void) { 

LocaleObject locale_object; 

UniChar uni lwr = L'c'; 

UniChar uni_upr; 

int rc; 

/*j<j<it'k'k'k-k-k-k-k'k'k'k'k-k'k-k'k-k-k'k-k-k-k-k-k-k'k'k-k'k-k'k-k-k-k-k-k'k-k-k-k-k'k'k'k'k'k'k'k-k-k-k-k'k-k-k-k-k'k'k'k'k-k J 

/* Assumes LANG environment variable set to a valid locale name, */ 
/* such as fr_FR */ 

/iciciciciciciciciciciciciciciciciciciciciciciciciciciciricicicicicicic-k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k J 

rc = UniCreateLocaleObject (UNI_UCS_STRING_PO INTER, 

(UniChar *)L"", &locale_object) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniCreateLocaleObj ect error: return code = %u\n", rc) ; 
return 1; 

} 

uni upr = UniTransUpper (locale_object, uni lwr); 
return (ULS_SUCCESS) ; 

} 


Conversion Functions 


It is expected that most of the processing by applications using the ULS will be done using UniChar* strings. 
Yet, many applications will need to export data to and import data from non-UCS encodings (for example, 
ASCII or EBCDIC). For this purpose, a set of functions are defined to perform conversions between UCS and 
non-UCS encodings. The Uconv name is used to indicate these functions. The Uconv functions are capable of 
doing only UCS conversions, such as converting to/from UCS. 

UniCreateUconvObiect 

UniCreateUconvObject creates and initializes a Uconv object. 

Format 


((include <uconv.h> 
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int UniCreateUconvObject 

(UniChar *cpname, UconvObject *uconv_object) 


Parameters 

cpname (UniChar *) 

Name of the UCS conversion. 


uconvobject (UconvObject *) 

The conversion object being returned. 

Returns 

return value (int) - returns 

Upon completion, UniCreateUconvObject returns one of the following: 
ULSSUCCESS 

Conversion object successfully initialized. 

ULS_IN VALID 

The conversion specified by cpname is not recognized by the implementation. 


Remarks 


UniCreateUconvObject returns a conversion object that describes a UCS-2 conversion between the code page 
specified by cpname and UCS. 

A conversion object remains valid until it is freed. 

The cpname field is normally the Unicode string IBM- followed by the decimal number of the code page. 
Other names may be used. UCONV tables are kept in the \language\codepage directory on the boot drive. 

If the cpname parameter contains an empty string, UniCreateUconvObject will create a conversion object 
based upon the value of the process codepage setting. 

UniCreateUconvObject allows modifiers to be concatenated onto cpname, these modifiers change the default 
behavior of conversion objects. The caller can concatenate the following modifiers onto cpname. 


Modifiers are separated from the conversion object name by an at sign (@), and multiple modifiers are 
separated by a comma (,). 


displaymask 


@map=data 

0map=display 

0map=cdra 

0map=clrf 


All characters less than space are controls, 
(default ) 

All characters less than space are glyphs. 
Use IBM standard control conversion. 

CR and LF are controls, others are glyphs. 


converttype 

0path=yes When performing Unicode conversions strings 

are assumed to contain pathnames. This 
setting is only applicable when converting 
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to or from DBCS codepages. 

(default ) 

0path=no When performing Unicode conversions strings 

are assumed to contain non path data. This 
setting is only applicable when converting 
to or from DBCS codepages. 


endian 

0endian=Source : Target 
0endian=Both 

Source applies to UniUconvFromUcs ; Target applies to 
UniUconvToUcs . If only one endian is given, it applies 
to both source and target. 

The endian type can be one of the following: 
system Use system endian, 

big Use big endian, 

little Use little endian. 

(default ) 

For example 0endian=iittle 

0endian=big: system 

options 


0sub=yes 
0sub=no 
0sub=to-ucs 
0sub=f rom-ucs 

0subchar=\xXX 

0subchar=\DD 


0subuni=\xXX\xXX 

0subuni=\xXXXX 


Perform substitutions when converting to and 
from Unicode. 

Do not perform substitutions when converting 
to and from Unicode. 

Only perform substitutions when converting to 
Unicode . 

Only perform substitutions when converting from 
Unicode . 

(default ) 

Where XX is a hex number 
Where DD is a decimal number 

The substitution character attribute specifies 
which character the conversion object should 
use when there is no identical character for 
a given code element while converting from 
Unicode . 

Where XX is a hex number 
Where XXXX is a hex number 

The substitution character attribute specifies 
which character the conversion object should 
use when there is no identical character for 
a given code element while converting to 
Unicode . 


Examples of typical usage: 
IBM-942@path=yes,map=display 


This example creates a conversion object based upon an IBM-942 
encoding. When conversions are performed all strings will be treated 
as pathnames and all characters less than space will be considered 
to be glyphs . 


@path=yes,sub=no 

This example creates a conversion object based upon the current 
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process codepage setting. When conversions are performed all strings 
will be treated as pathnames and no substitutions will occur. 

IBM-850@path=no,sub=yes 


This example creates a conversion object based upon an IBM-850 
encoding. When conversions are performed all strings will be treated 
as non pathnames and substitutions will occur when converting to and 
from Unicode if necessary. 

UniCreateUconvObject returns a conversion object in uconvobject for use in subsequent calls to either 

UniUconvFromUcs or UniUconvToUcs. 

Related Functions 

• UniFreeUconvObject 

• UniQueryUconvObject 

• UniSetUconvObject 


Example 


This example shows how to create a conversion object. 

#include <stdio.h> 

#include <uconv.h> 
int main (void) { 

UconvObject uconv_object = NULL; 
int rc = ULS_SUCCESS ; 

^******************************************************************** i 

/* Create a conversion object based upon the process codepage */ 

/* setting with the path modifier set */ 

J***ititititj(j(j(j(itit-k'k-k-k-k-k-k-k-k-k-k-k-k-k-k'k'k'k'k'k'k'k-k-k-k-k-k-k-k-k-k'k'k-k'k-k-k'k-k-k-k-k'k-k-k-k-k'k'k'k'k'k-k-k-k J 

rc = UniCreateUconvObject ( (UniChar *) L"@path=yes", &uconv_object) ; 
if (rc ! = ULS_SUCCESS ) { 

printf ("UniCreateUconvObject error: return code = %u\n", rc) ; 
return 1; 

} 

return ULS_SUCCESS; 

} 


UniFreeUconvObject 

UniFreeUconvObject frees a conversion object. 

Format 


#include <uconv.h> 


int UniFreeUconvObject 

(UconvObject uconv object) 
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Parameters 

uconvobject (UconvObject) 

Conversion object created by a call to UniCreateUconvObject. 

Returns 

return value (int) - returns 

Upon completion, UniFreeUconvObject returns one of the following values: 


ULS_SUCCESS 

All resources associated with uconv have been successfully freed. 

ULSBADOBJECT 

The uconv object argument is not a valid conversion object. 


Remarks 

UniFreeUconvObject closes the conversion object. 

Related Functions 

• UniCreateUconvObject 

• UniQueryUconvObject 

• UniSetUconvObject 

Example 


This example shows how to create and free a conversion object, 
((include <stdio.h> 

((include <uconv.h> 
int main (void) { 

UconvObject uconv_object = NULL; 
int rc = ULS SUCCESS; 


rc = UniCreateUconvObject ( (UniChar *) L"@path=yes", &uconv_object) ; 
if (rc ! = ULS_SUCCESS ) { 

printf ( "UniCreateUconvObject error: return code = %u\n", rc) ; 
return 1; 

} 

rc = UniFreeUconvObject (uconv_object) ; 
if (rc ! = ULS_SUCCESS ) { 

printf ( "UniFreeUconvObject error: return code = %u\n", rc) ; 
return 1; 

} 

return ULS SUCCESS; 



/* Create a conversion object based upon the process codepage 
/* setting with the path modifier set 


*/ 

*/ 



} 


UniMapCpToUcsCp 
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UniMapCpToUcsCp converts a code page number into a code page represented as a UniChar string that is 
acceptable as input to UniCreateUconvObject. 

Format 


((include <uconv.h> 


int UniMapCpToUcsCp 

(unsigned long ulCodepage, UniChar *ucsCodepage, sizet n) 


Parameters 

ulCodepage (unsigned long) - input 

A code page as returned from DosQueryCp. If the value is zero the current process codepage value will 
be used in determining the returned Unicode string. 

ucsCodepage (UniChar *) - output 

A buffer for placing the Unicode string. 

n (size t) - input 

Size of the ucsCodepage buffer in Unicode characters. This should be at least 12 Unicode characters. 

Returns 

retcode (int) - returns 
Error code. 

UniMapCpToUcsCp returns one of the following values: 

ULS_SUCCESS 

The code page number was successfully converted to a Unicode string. 

ULS_IN VALID 

An invalid code page number or buffer was passed in; the contents of ucsCodepage are 
undefined. 

Related Functions 

• UniMapCtryToLocale 

Example 


This example shows how to convert a codepage number to a Unicode string, 
((include <stdio.h> 

((include <uconv.h> 
int main (void) { 

UniChar ucs_code_page [ 12 ] ; 

size_t num_elems = 12; 

UconvObject uconv_object = NULL; 
int rc = ULS SUCCESS; 
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j • k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k j 

/* Convert a code page number to a unichar string */ 

/******************************************************************** j 


rc = UniMapCpToUcsCp(850, ucs_code_page, numelems); 

if (rc ! = ULS_SUCCESS ) { 

printf ( "UniMapCpToUcsCp error: return code = %u\n", rc) ; 
return 1; 

} 

rc = UniCreateUconvObject (ucs_code_page, &uconv_object) ; 
if (rc ! = ULS_SUCCESS ) { 

printf ("UniCreateUconvObject error: return code = %u\n", rc) ; 
return 1; 

} 

return ULS SUCCESS; 


} 


UniQueryUconvObiect 

UniQueryUconvObject queries the attributes of a conversion object. 

Format 


((include <uconv.h> 


int UniQueryUconvObject 

(UconvObject uobj, uconvattributet *attr, sizet size, char first [256] , char other[256], 
udcranget udcrange[32]) 


Parameters 

uobj (UconvObject) - input 

The conversion object created by a call to UniCreateUconvObject. 

attr (uconv_attribute_t *) - output 

Pointer to uconv attribute t; receives attribute information. 


size (size t ) - input 

Specifies the size of the attribute buffer. This must be at least as large as version 0 of the 
uconv attribute t structure. 


first[256] (char) - output 

Gives an array of starting bytes for a multibyte character set. For some forms of stateful code pages, the 
length is based on state and not this table. If this parameter is NULL, no value is returned. Each byte 
has one of the following values: 

1 

Valid single byte character. 

2 
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for a double-byte character. 
3 

for a triple-byte character. 
255 

code point. 


other[256] (char) - output 

An array indicating when the byte is used a secondary byte in a multi-byte sequence. This is used to 
allocate buffers. There are two possible values for each byte: 

0 

This is not used as a secondary character. 

1 

This is used as a secondary character. 


udcrange[32] (udcrange t) - output 

A set of ranges of characters that make up the user-defined character range. 

Returns 

retcode (int) - returns 
Error code. 

UniQueryUconvObject returns one of the following values: 
ULSSUCCESS 

The conversion object data was successfully returned 


Remarks 

UniQueryUconvObject queries the attributes and characteristics of the given conversion object. The attributes 
are used to modify the default conversion. 

The substitution character attributes specify to the conversion object how to perfonn in cases that there is no 
identical character for a given code element. UniQueryUconvObject may be used to query the substitution 
characters used by the conversion. 

Some of these are static and bound to the conversion table; others are settable through UniSetUconvObject 

The attr, first, other, and udcrange parameters can be NULL to indicate that this data should not be returned. 

See the uconv attribute t to see the conversion object attributes; the structure indicates which fields can be 
queried and which can be set through UniSetUconvObject. 

Related Functions 

• UniCreateUconvObject 

• UniFreeUconvObject 
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• UniSetUconvObject 


Example 


This example shows how to query a conversion object. 

((include <stdio.h> 

((include <uconv.h> 
int main (void) { 
uconv_attribute_t attr; 

UconvObject uconv_object = NULL; 

int rc = ULS_SUCCESS ; 

/* Create a conversion object based upon the process codepage */ 

/* setting with the path modifier set */ 

J*j<j<ititititj(*j<j<-k'k'k'k-k-k-k-k-k-k-k-k'k-k-k-k-k'k'k'k'k'k'k-k-k-k-k-k-k-k-k-k-k'k'k'k'k'k'k'k-k-k-k-k'k-k-k-k-k'k'k'k'k'k-k-k-k J 

rc = UniCreateUconvObject ( (UniChar *) L"@path=yes", &uconv_object) ; 
if (rc ! = ULS_SUCCESS ) { 

printf ("UniCreateUconvObject error: return code = %u\n", rc) ; 
return 1; 

} 

/* Query the conversion object */ 

rc = UniQueryUconvObject (uconv_object, Sattr, 

sizeof (uconv_attribute_t) , NULL, 

NULL, NULL) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ("UniQueryUconvObject error: return code = %u\n", rc) ; 
return 1; 

} 

return ULS_SUCCESS; 

} 


UniSetUconvObject 

UniSetUconvObject sets the attributes of a conversion object. 

Format 


((include <uconv.h> 


int UniSetUconvObject 

(UconvObject uconvobject, uconvattributet *attr_t) 


Parameters 

uconv object (UconvObject) - input 

The conversion object created by a call to UniCreateUconvObject. :evallist. :eparm. 


attr t (uconv attribute t *) - input 

The uconv attribute t structure, which the caller sets with values of the conversion object attributes. 
The caller can set these fields: 
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options 

Substitution options, which can have one of these values: 

UCONVOPTIONSUBSTITUTIONFROMUNICODE 
UCONVOPTIONSUBSTITUTIONTOUNICODE 
UCONV OPTION SUBSTITUTION BOTH 


endian 

Source and target endian. Thsi is a structure containing a source and target endian field. Source 
applies to UniUconvFromUcs; target applies to UniUconvToUcs. Each of the fields can contain 
one of the following values: 

0x000 

Use system endian. 

Oxfeff 

Use big endian. 

Oxfffe 

Use little endian. 

displaymask 

A 32-bit display and data mask. Each bit represents a control character below space (l«char). If 
the bit is 0, the character is treated as a display glyph. If the bit is 1, the character is treated as a 
control. There are several predefined values for this mask, but any value can be used: 

DSPMASK DATA 

All characters less than space are controls. 

DSPMASK DISPLAY 

All characters less than space are glyphs. 

DSPMASK CRLF 

CR and LF are controls: Others are glyphs. 

converttype 

Conversion type. This is a set of flags. The following flags exist and can be ORed together: 
CVTTYPE CTRL7F 

Treat the 0x7f character as a control. 

CVTTYPE CDRA 

Use IBM standard control conversion. If this bit is not set, controls are converted to an 
equal value. Some conversions always do control conversions. 

CVTTYPE PATH 

When performing Unicode conversions strings are assumed to contain pathnames. This 
setting is only applicable when converting to or from DBCS codepages. 

subcharlen 

Code page substitution length. This can be a value between 1 and 13 to indicate the substitution length. 
It may not exceed the maximum size character in the encoding. A value of zero indicates that the 
substitution character from the conversion table should be used. 

subchar 

Substitution bytes. This is the actual value whose length is specified by subchar len. 

subunilen 

Unicode substitution length. This can be either 0 or 1 . A zero indicates that the Unicode 
substitution from the conversion table should be used. 

subuni 

If subuni len is set to 1 , the first element in this array gives the Unicode substitution character. 


135 of 154 



Unicode Functions (OS/2 Warp) 


state 


When the state is set to 0, the conversion object is put into the base conversion state. 


Returns 

return value (int) - returns 
Return Codes 
ULS_SUCCESS 

Indicates success. 

ULSBADATTR 

Indicates an invalid parameter. 

Remarks 

UniSetUconvObject sets the attributes of the given conversion object. The attributes are used to modify the 
default conversion. It is left up to each conversion to decide which attributes it will recognize. 

The substitution character attributes specify to the conversion object how to perfonn in cases that there is no 
identical character for a given code element. 

Remarks 

This example sets the displaymask to all display and path to yes, meaning all code points below space are 
mapped as glyphs and not as controls. It also treats data as pathnames. To modify only some attributes, a 
query should first be done using UniQueryUconvObject. 

Related Functions 

• UniCreateUconvObject 

• UniFreeUconvObject 

• UniQueryUconvObject 

Example 


This example shows how to set a conversion object. 
#include <stdio.h> 

((include <uconv.h> 
int main (void) { 
uconv_attribute_t attr; 

UconvObject uconv_object = NULL; 

int rc = ULS SUCCESS; 


rc = UniCreateUconvObject ( (UniChar *) L"@path=yes", &uconv_object) ; 
if (rc ! = ULS_SUCCESS ) { 

printf ("UniCreateUconvObject error: return code = %u\n", rc) ; 
return 1; 

} 

/* Query the conversion object */ 

rc = UniQueryUconvObject (uconv_object, Sattr, 



/* Create a conversion object based upon the process codepage 
/* setting with the path modifier set 


*/ 

*/ 



sizeof (uconv attribute t) , NULL 
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NULL, NULL) ; 

if (rc ! = ULS_SUCCESS ) { 

printf ("UniQueryUconvObject error: return code = %u\n", rc) ; 
return 1; 

} 

/* Turn the path modifier and display attributes on */ 
attr . converttype = attr . converttype | CVTTYPE_PATH; 
attr .displaymask = DSPMASK_DISPLAY; 
rc = UniSetUconvObject (uconv_object, &attr) ; 
if (rc ! = ULS_SUCCESS ) { 

printf ( "UniSetUconvObj ect error: return code = %u\n", rc) ; 
return 1; 

} 

return ULS SUCCESS; 


} 


UniUconvFromUcs 


UniUconvFromUcs converts UCS characters to code page characters. 

Format 


((include <uconv.h> 

int UniUconvFromUcs 

(UconvObject uconvobject, UniChar **ucsbuf, sizet *UniCharsleft, void **outbuf, 
sizet *outbytesleft, size t *nonidentical) 


Parameters 

uconv object (UconvObject) 

Conversion object created by a call to UniCreateUconvObject. 


ucsbuf (UniChar **) 
Input buffer. 


UniCharsleft (size t *) 

Number of UniChar elements in ucsbuf. 


outbuf (void **) 

Output buffer. 

outbytesleft (size_t *) 

Size of outbuf, in units of bytes. 


nonidentical (size t *) 

Number of nonidentical conversions. 

Returns 


137 of 154 


Unicode Functions (OS/2 Warp) 


return value (int) - returns 

UniUconvToUcs returns one of the following values: 

ULS_SUCCESS 

Conversion successful. 

ULSBUFFERFULL 

Input conversion stopped due to lack of space in the output buffer. 

ULSILLEGALSEQUENCE 

Input conversion stopped due to an incomplete character or shift sequence at the end of the input 
buffer. This condition will be given when the last UniChar element is recognized as a combining 
character. 

ULS_IN VALID 

The uconv_object argument is not a valid, open conversion object. 

UniUconvFromUcs updates the variables pointed to by the arguments to reflect the extent of the 
conversion and returns, in nonidentical, the number of substitution (nonidentical) conversions 
perfonned. If the entire string in the input buffer is converted, the value pointed to by UniCharsleft 
will be 0. If the input conversion is stopped due to any condition mentioned above, the value pointed to 
by UniCharsleft will be nonzero. If any error occurs, UniUconvToUcs returns a nonzero value. 

Remarks 

UniUconvFromUcs converts a sequence of code elements, in the array specified by ucsbuf, into a sequence of 
corresponding characters in another code page, in the array specified by outbuf. The code page of the outbuf 
is the string specified in the UniCreateUconvObject call that returned the conversion object, uconv_object. 
The ucsbuf argument points to a variable that points to the first UniChar in the input buffer, and the 
UniCharsleft indicates the number of UniChar elements to the end of the buffer to be converted. The outbuf 
argument points to a variable that points to the first available character in outbuf, and outbytesleft indicates 
the number of bytes available to the end of the buffer. 

If the outbuf buffer is not large enough to hold the entire converted input, conversion stops just prior to the 
input UniChar that would cause the output buffer to overflow. The variable pointed to by ucsbuf is updated to 
point to the UniChar following the last UniChar successfully used in the conversion. The value pointed to by 
outbytesleft is decremented to reflect the number of bytes still available in outbuf. 

If UniUconvFromUcs encounters a code element in the ucsbuf that is legal, but for which an identical 
character does not exist in the target code page, UniUconvFromUcs replaces the character with a predefined 
substitution character, if the attributes of the conversion object allow this operation. If substitution is not 
selected, an error is returned and conversion stops after the previous successfully converted UniChar. 

Related Functions 

• UniUconvToUcs 

• UniStrFromUcs 

• UniStrToUcs 


Example 


This example shows how to convert a Unicode string to code page characters. 
#include <stdio.h> 
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((include <uconv.h> 
int main (void) { 

UconvObject uconv_object = NULL; 
int rc = ULS_SUCCESS ; 

size_t out_bytes_left; 

size_t uni_chars_left; 

size_t num_subs; 

size_t char_buf_size = 50; 

char char_buffer [50] ; 

char *pout_char_str ; 

UniChar *pin_uni__str ; 

UniChar uni_data [ ] = L"UniCode string to convert"; 

/icicicic-k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k-k-k'k'k'k'k'k'k'k'k 

/* Create a conversion object based upon the process 

J icicic'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k-k-k-k-k'k'k'k'k'k'k'k'k 


•k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k 

codepage 

•k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k 


*/ 

*/ 

*/ 


rc = UniCreateUconvObject ( (UniChar *)L"", &uconv_object) ; 
if (rc ! = ULS_SUCCESS ) { 

printf ( "UniCreateUconvObject error: return code = %u\n", rc) ; 
return 1; 


j iciciciciciciciciciciciciciciciciciciciciriciciciciciciciricicicicicicicicicicicicicicic'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k j 

/ * pin_uni_str points to the Unicode string to be converted to */ 

/* codepage characters */ 

J ****ititit'k-k-k-k-k'k'k'k'k'k'k-k'k-k'k'k-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k'k-k-k-k-k'k-k-k'k'k'k'k-k j 

pout_char_str = char_buffer; 
pin_uni_str = uni_data; 

uni^chars left = UniStrlen (pin_uni_str ) +1 ; 
out_bytes_lef t = char_buf_size; 

/* make call to convert Unicode string to codepage characters */ 

/j(j<j<*ititititj(j<-k-k'k'k'k-k-k-k-k-k-k-k-k-k-k-k-k-k-k'k'k'k'k-k-k-k-k-k-k-k'k-k-k-k-k-k'k-k'k-k-k-k-k-k-k-k'k-k-k-k-k'k'k'k'k-k'k'k-k J 

rc = UniUconvFromUcs (uconv_object, &pin_uni_str , &uni_chars_left, 

(void **) &pout_char_str , &out_bytes_left, 

&num_subs ) ; 

if (rc != ULS_SUCCESS && uni_chars_lef t > 0) { 

printf ( "UniUconvFromUcs error: return code = %u\n", rc) ; 
printf ( "Unicode string was not completely converted\n" ) ; 
return 1; 

} 


return ULS_SUCCESS; 

} 


UniUconvToUcs 


UniUconvToUcs converts a code page string to a UCS string. 

Format 


((include <uconv.h> 

int UniUconvToUcs 

(UconvObject uconv object, void **inbuf, size t *inbytesleft, UniChar **ucsbuf, 
size t *UniCharsleft, size t *nonidentical) 
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Parameters 

uconv_object (UconvObject) 

Conversion object created by a call to UniCreateUconvObject. 

inbuf (void **) 

Input buffer. 

inbytesleft (size_t *) 

Size of inbuf, in units of bytes. 

ucsbuf (UniChar **) 

Output buffer. 

UniCharsleft (size t *) 

Number of Unichar elements in ucsbuf. 

nonidentical (size t *) 

Number of non-identical conversions. 

Returns 

return value (int) - returns 

UniUconvToUcs returns one of the following values: 

ULSSUCCESS 

Conversion successful. 

UL S_IN VALID 

Input conversion stopped due to an error condition such as lack of buffer space. 

UniUconvToUcs updates the variables pointed to by the arguments to reflect the extent of the 
conversion and returns, in nonidentical, the number of substitutions (non-identical) conversions 
performed. If the entire string in the input buffer is converted, the value pointed to by inbytesleft will 
be zero. If the input conversion is stopped due to any condition mentioned above, the value pointed to 
by inbytesleft will be non zero and a non zero value is returned to indicate the condition. If an error 
occurs, UniUconvToUcs returns a non zero value. 


Remarks 

UniUconvToUcs converts a sequence of characters encoded in one code page, in the array specified by inbuf, 
into a sequence of corresponding UCS code elements, in the array specified by ucsbuf. The code page of the 
inbuf is the string specified in the UniCreateUconvObject call that returned the conversion object, 
uconv_object. The inbuf argument points to a variable that points to the first byte in the input buffer, and the 
inbytesleft indicates the number of bytes to the end of the buffer to be converted. The ucsbuf argument points 
to a variable that points to the first available UniChar in ucsbuf, and UniCharsleft indicates the number of 
UniChar elements available to the end of the buffer. 

If a sequence of bytes within inbuf does not form a valid character in the specified code page and substitution 
to UCS is not turned on, conversion stops after the previous successfully converted character. If the input 
buffer ends with an incomplete character, conversion stops after the previous successfully converted bytes. If 
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the ucsbuf buffer is not large enough to hold the entire converted input, conversion stops just prior to the 
input bytes that would cause the output buffer to overflow. The variable pointed to by inbuf is updated to 
point to the byte following the last byte successfully used in the conversion. The value pointed to by 
UniCharsleft is decremented to reflect the number of UniChar elements still available in ucsbuf. 

Related Functions 

• UniUconvFromUcs 

• UniStrFromUcs 

• UniStrToUcs 


Example 


This example shows how to convert code page encoded characters to Unicode, 
((include <stdio.h> 


((include <string.h> 
((include <stdlib.h> 


((include <uconv.h> 
int main (void) { 

UconvObject uconv_object = NULL; 
int rc = ULS_SUCCESS ; 

size_t in_bytes_lef t; 

size_t uni_chars_left; 

size_t num_subs; 

int uni_buf_length = 50; 

UniChar uni^buffer [50] ; 

UniChar *pout_uni_str ; 

char char_data[] = "Character string to convert"; 

char *pin_char_str ; 

/j<j<*i?jtjtjt*-k-k-k'k'k'k'k'k-k-k-k-k-k-k-k-k-k-k-k-k'k'k'k'k'k'k'k-k-k-k-k'k-k-k'k'k'k-k-k'k-k-k'k-k-k-k-k'k-k-k'k-k'k'k-k-k'k'k-k 

/* Create a conversion object based upon the process codepage 

/iciciciciciciciciciciciriciciriciciciciciciciciciciciciriciciciciciciciciciciric'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k 


*/ 

*/ 

*/ 


rc = UniCreateUconvObject ( (UniChar *)L"", &uconv_object) ; 
if (rc ! = ULS_SUCCESS ) { 

printf ( "UniCreateUconvObject error: return code = %u\n", rc) ; 
return 1; 


I ********************************************************************* i 

/* pin_char_str points to the character string to be converted to */ 
/* Unicode characters */ 

j ********************************************************************* j 

pout_uni_str = uni_buffer; 
pin_char_str = char_data; 
uni_chars_lef t = uni_buf length; 

in_bytes_lef t = ( strlen (char_data) + 1 ) * sizeof (char) ; 

/* make call to convert codepage character string to a Unicode string */ 

/•k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k'k'k'k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k'k'k-k-k-k'k-k-k-k-k'k-k-k'k-k-k-k-k-k j 

rc = UniUconvToUcs (uconv_object, (void **) &pin_char_str , &in_bytes_lef t, 
&pout_uni_str , &uni_chars_left, 

&num_subs) ; 

if (rc != ULS_SUCCESS && in_bytes_lef t > 0) { 

printf ( "UniUconvToUcs error: return code = %u\n", rc) ; 

printf ( "Character string was not completely converted to UnicodeXn"); 
return 1; 
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} 

return ULS_SUCCESS; 

} 


UniStrFromUcs 


UniStrFromUcs converts a UCS string to a code page string. 

Format 


((include <uconv.h> 

int UniStrFromUcs 

(UconvObject uconvobject, char *outbuf, UniChar *ucsstr, int size) 


Parameters 

uconv object (UconvObject) 

Conversion object created by a call to UniCreateUconvObject. 
outbuf (char *) 

Output buffer to hold converted string. 

ucsstr (UniChar *) 

Null tenninated Unicode string. 

size (int ) 

number of bytes that output buffer can hold 

Returns 

return value (int) - returns 

UniStrFromUcs returns one of the following values: 

ULSSUCCESS 

Conversion successful. 

ULSBADOBJECT 

The uconv_object argument is not a valid, open conversion object. 

ULSBUFFERFULL 

Input conversion stopped due to lack of space in the output buffer. 

ULSILLEGALSEQUENCE 

Input conversion stopped due to an input byte that does not belong to the input code page. 
UniStrFromUcs always perfonns conversions with substitution on. 

Remarks 
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UniStrFromUcs converts a sequence of code elements up to and including the null terminator, in the array 
specified by ucsstr, into a sequence of corresponding characters in another code page in the array specified by 
outbuf. The code page of outbuf is the string specified in the UniCreateUconvObject call that returned the 
conversion object, uconv_object. The ucsstr argument points to a variable that points to the first UniChar in 
the input bufer. The outbuf argument points to a variable that points to the first available character in outbuf, 
and size indicates the number of bytes available to the end of the buffer. 

If the outbuf buffer is not large enough to hold the entire converted input, conversion stops just prior to the 
input UniChar that would cause the output buffer to overflow. 

If UniStrFromUcs encounters a code element in the ucsstr that is legal, but for which an identical character 
does not exist in the target code page, UniStrFromUcs replaces the character with a predefined substitution 
character. 

Related Functions 

• UniUconvFromUcs 

• UniUconvToUcs 

• UniStrToUcs 

Example 


This example shows how to convert a Unicode string to code page characters. 
#include <stdio.h> 

#include <uconv.h> 
int main (void) { 

UconvObject uconv_object = NULL; 
int rc = ULS_SUCCESS ; 

size_t buf_size = 50; 

char char_buffer [50] ; 

UniChar uni data [ ] = L"UniCode string to convert"; 

/-k'k'k-k-k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-k'k'k'k-k-k-k-k-k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k-k-k-k-k-k'k-k'k-k-k-k-k-k'k'k'k'k'k'k'k-k j 

/* Create a conversion object based upon the process codepage */ 

Jiciciciciciciciciciciciciciriciciciciciciciciciciciciciriririricicicicicicicicicicic'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k j 

rc = UniCreateUconvObject ( (UniChar *)L"", &uconv_object) ; 
if (rc ! = ULS_SUCCESS ) { 

printf ("UniCreateUconvObject error: return code = %u\n", rc) ; 
return 1; 

} 


I ********************************************************************* j 

/* make call to convert Unicode string to codepage characters */ 

j •k-k-k-k'k-k'k-k-k-k-k-k'k'k'k'k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k'k-k-k-k-k'k-k'k-k-k-k-k-k-k-k'k-k-k-k-k-k-k'k'k'k'k'k'k-k J 

rc = UniStrFromUcs (uconv_object, char_buffer, uni_data, buf_size) ; 
if (rc ! = ULS_SUCCESS ) { 

printf ( "UniStrFromUcs error: return code = %u\n", rc) ; 
printf ( "Unicode string was not completely converted\n" ) ; 
return 1; 

} 


return ULS_SUCCESS; 

} 
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UniStrToUcs 


UniStrToUcs converts a code page string to a UCS string. 

Format 


((include <uconv.h> 

int UniStrToUcs 

(UconvObject uconvobject, void **inbuf, sizet *inbytesleft, UniChar **ucsbuf, 
sizet *UniCharsleft, size t *nonidentical) 


Parameters 

uconv object (UconvObject) 

Conversion object created by a call to UniCreateUconvObject. 


inbuf (void **) 
Input buffer. 


inbytesleft (size_t *) 

Size of inbuf, in units of bytes. 

ucsbuf (UniChar **) 

Output buffer. 

UniCharsleft (size t *) 

Number of Unichar elements in ucsbuf. 


nonidentical (size t *) 

Number of non-identical conversions. 

Returns 

return value (int) - returns 

UniUconvToUcs returns one of the following values: 

ULSSUCCESS 

Conversion successful. 

ULSBADOBJECT 

The uconv_object argument is not a valid, open conversion object. 

ULSBUFFERFULL 

Input conversion stopped due to lack of space in the output buffer. 

ULSILLEGALSEQUENCE 

Input conversion stopped due to an input byte that does not belong to the input code page. 
ULS_IN VALID 

Input conversion stopped due to an incomplete character or shift sequence at the end of the input 
buffer. 
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UniUconvToUcs updates the variables pointed to by the arguments to reflect the extent of the 
conversion and returns, in nonidentical, the number of substitutions (non-identical) conversions 
perfonned. If the entire string in the input buffer is converted, the value pointed to by inbytesleft will 
be zero. If the input conversion is stopped due to any condition mentioned above, the value pointed to 
by inbytesleft will be non zero and a non zero value is returned to indicate the condition. If an error 
occurs, UniUconvToUcs returns a non zero value. 

Remarks 

UniUconvToUcs converts a sequence of characters encoded in one code page, in the array specified by inbuf, 
into a sequence of corresponding UCS code elements, in the array specified by ucsbuf. The code page of the 
inbuf is the string specified in the UniCreateUconvObject call that returned the conversion object, 
uconv_object. The inbuf argument points to a variable that points to the first byte in the input buffer, and the 
inbytesleft indicates the number of bytes to the end of the buffer to be converted. The ucsbuf argument points 
to a variable that points to the first available UniChar in ucsbuf, and UniCharsleft indicates the number of 
UniChar elements available to the end of the buffer. 

If a sequence of bytes within inbuf does not form a valid character in the specified code page and substitution 
to UCS is not turned on, conversion stops after the previous successfully converted character. If the input 
buffer ends with an incomplete character, conversion stops after the previous successfully converted bytes. If 
the ucsbuf buffer is not large enough to hold the entire converted input, conversion stops just prior to the 
input bytes that would cause the output buffer to overflow. The variable pointed to by inbuf is updated to 
point to the byte following the last byte successfully used in the conversion. The value pointed to by 
UniCharsleft is decremented to reflect the number of UniChar elements still available in ucsbuf. 

Related Functions 

• UniUconvFromUcs 

• UniUconvToUcs 

• UniStrFromUcs 

Example 


This example shows how to convert code page encoded characters to Unicode. 
#include <stdio.h> 

#include <string.h> 

#include <stdlib.h> 


#include <uconv.h> 
int main (void) { 

UconvObject uconv_object = NULL; 
int rc = ULS_SUCCESS ; 

size_t in_bytes_lef t; 

size_t uni_chars_left; 

size_t num_subs; 

int uni_buf_length = 50; 

UniChar uni_buffer [50] ; 

UniChar *pout_uni_str ; 

char char_data[] = "Character string to convert"; 

char *pin_char_str ; 

/•k'k'k-k'k-k-k'k'k-k'k-k-k-k-k'k-k-k'k-k-k-k'k'k-k'k-k-k'k-k-k'k'k'k'k-k-k-k-k'k'k'k'k-k'k-k-k'k-k-k'k-k-k-k-k'k-k-k'k-k'k-k-k'k'k'k'k-k. 
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/* Create a conversion object based upon the process codepage */ 

^******************************************************************** j 

rc = UniCreateUconvObject ( (UniChar *)L"", &uconv_object) ; 
if (rc ! = ULS_SUCCESS ) { 

printf ("UniCreateUconvObject error: return code = %u\n", rc) ; 
return 1; 

} 

I ********************************************************************* j 

/ * pin_char_str points to the character string to be converted to */ 
/* Unicode characters */ 

pout_uni_str = uni_buffer; 
pin_char_str = char_data; 
uni^chars left = uni_buf_length; 

in_bytes_lef t = ( strlen (char_data) + 1 ) * sizeof (char) ; 

/* make call to convert codepage character string to a Unicode string */ 

rc = UniUconvToUcs (uconv_object, (void **) &pin_char_str , &in_bytes_lef t, 
&pout_uni_str , &uni_chars left, 

&num_subs) ; 

if (rc != ULS_SUCCESS && in_bytes_lef t > 0) { 

printf ( "UniUconvToUcs error: return code = %u\n", rc) ; 

printf ( "Character string was not completely converted to UnicodeXn"); 
return 1; 

} 

return ULS_SUCCESS; 

} 


ULS Data Types 

The following data types are used by the Unicode functions. 


AttrObiect 

AttrObject is used to determine character classifications. 


typedef void *AttrObject; 


cony endian t 


conv endian t Infonnation about the source and target endian. 
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typedef struct _conv_endian_rec { 
unsigned short source; 

unsigned short target; 

} conv endian t; 


Parameters 


source (unsigned short) 
Source infonnation. 
target (unsigned short) 
Target information. 


Localeltem 


Localeltem is used to identify a language or cultural item within a locale. 


typedef int Localeltem; 


LocaleObiect 

LocaleObject is used by APIs that require language or cultural sensitive processing. 


typedef void *LocaleObject; 


LocaleToken 


Locale Token is used as a shorthand method for identifying locales. 


typedef unsigned int LocaleToken; 
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struct UniLconv 


struct UniLconv describes the locale conventions. 


struct UniLconv { 

UniChar *decimal_point; 
UniChar *thousands_sep; 
short ^grouping; 

UniChar *int_curr_symbol; 
UniChar *currency_symbol; 
UniChar *mon_decimal_point; 
UniChar *mon_thousands_sep; 
short *mon_grouping; 

UniChar *positive_sign; 
UniChar *negative_sign; 
short int_f rac_digits ; 

short frac_digits; 

short p_cs_precedes ; 

short p_sep_by_space; 

short n_cs_precedes ; 

short n_sep_by_space; 

short p_sign_posn; 

short n_sign_posn; 

short os2_mondecpt; 

UniChar *debit_sign; 

UniChar *credit_sign; 

UniChar *left_parenthesis; 
UniChar *right_parenthesis ; 


Parameters 

decimal_point (UniChar *) 

Non-monetary decimal point, 
thousands sep (UniChar *) 

Non-monetary thousands separator, 
grouping (short *) 

Size of each group of digits in non-monetary quantities, 
int curr symbol (UniChar *) 

International currency symbol and separator, 
currency symbol (UniChar *) 

Local currency symbol. 
mon_decimal_point (UniChar *) 

Monetary decimal point, 
mon thousands sep (UniChar *) 

Monetary thousands separator. 


148 of 154 


Unicode Functions (OS/2 Warp) 


mon grouping (short *) 

Size of each group of digits in monetary quantities, 
positive sign (UniChar *) 

Non-negative values sign. 
negative_sign (UniChar *) 

Negative values sign, 
int frac digits (short) 

Number of fractional digits for international currency. 
frac_digits (short) 

Number of fractional digits for local currency, 
pcspreccdes (short) 

Nonnegative currency symbol 1 -precedes, O-succeeds. 
p scp by spacc (short) 

Nonnegative currency symbol 1 -space, 0-no space, 
n cs prccedcs (short) 

Negative currency symbol 1 -precedes, O-succeeds. 
n scp by spacc (short) 

Negative currency symbol 1 -space, 0-no space. 
p_sign_posn (short) 

Positioning of nonnegative monetary sign. 
n_sign_posn (short) 

Positioning of negative monetary sign. 
os2_mondecpt (short) 

OS2 currency symbol positioning, 
debit sign (UniChar *) 

Non-negative valued debit monetary symbol, 
credit sign (UniChar *) 

Negative valued credit monetary symbol. 
left_parenthesis (UniChar *) 

Negative valued left parenthesis monetary symbol. 
right_parenthesis (UniChar *) 

Negative valued right parenthesis monetary symbol. 


uconv attribute t 


uconv attribute t This structure describes the attributes and characteristics of a conversion object. All of these 
fields are queryable through UniQueryUconvObject. Some of the fields are settable through 
UniSetUconvObject; these are marked in the descriptions. 


typedef struct _uconv_attribute_t { 
unsigned long version; 
char mb_min_len; 

char mb_max_len; 

char usc_min_len; 

char usc_max_len; 

unsigned short esid; 
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char options; 

char state; 

conv_endian_t endian; 
unsigned long displaymask; 
unsigned long converttype; 
unsigned short subchar_len; 
unsigned short subuni_len; 
char subchar [16]; 

UniChar subuni [8]; 

} uconv_attribute_t; 

typedef uconv_attribute_t *uconv_attribute_t; 


Parameters 

version (unsigned long) 

Version (must be zero). Settable, 
mbminlen (char) 

Minimum character size, 
mbmaxlen (char) 

Maximum character size, 
uscminlen (char) 

UCS minimum character size, 
uscmaxlen (char) 

UCS maximum character size, 
esid (unsigned short) 

Encoding scheme ID. 
options (char) 

Substitution options. Settable, 
state (char) 

Current state. Settable, 
endian (conv endian t) 

Source and target chain. Settable, 
displaymask (unsigned long) 

Display and data mask. Settable, 
converttype (unsigned long) 

Conversion type. Settable, 
subchar len (unsigned short) 

MBCS sub-character length. Settable, 
subuni len (unsigned short) 

Unicode sub-character length. Settable. 
subchar[16] (char) 

MBCS sub-characters. Settable, 
subuni [8] (UniChar) 

Unicode sub-characters. Settable. 


UconvObject 


150 of 154 


Unicode Functions (OS/2 Warp) 


UconvObject is used by APIs that convert to and from UniCode. 


typedef void *UconvObject; 


UNICTYPE 


The UNICTYPE structure provides a range of information regarding the type of a character. 


typedef struct { 
USHORT itype; 
CHAR bidi; 

CHAR charset; 
USHORT extend; 
USHORT codepage; 
} UNICTYPE; 


Parameters 

itype (USHORT) 

XPG/4 type attributes (CTYPE1). 

bidi (CHAR) 

BiDi type attributes (CTYPE2). 

charset (CHAR) 

Character set (CHARSET). 

extend (USHORT) 

Win32 Extended attributes (CTYPE3). 

codepage (USHORT) 

Codepage bits. 


udcrange t 

udcrange t provides a set of ranges of characters that make up the user-defined character range. 
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typedef struct { 

unsigned short first; 

unsigned short last; 

} udcrange_t; 


Parameters 

first (unsigned short) 
First code point. 

last (unsigned short) 
Last code point. 


ulsBool 


ulsBool 


typedef int ulsBool; 

0 - FALSE 

1 - TRUE 


UniChar 


A Unicode character. Unicode is code that is independent of language and culture, and supports multiple 
simultaneous character sets. 


typedef unsigned short UniChar; 


XformObiect 

XformObject is used to perform string transformations. 
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typedef void *XformObject; 


Notices 


Unicode Functions (OS/2 Warp) 

Second Edition (October 1997) 

The following paragraph does not apply to the United Kingdom or any country where such provisions 
are inconsistent with local law: 

INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" 
WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT 
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A 
PARTICULAR PURPOSE. 

Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this 
statement may not apply to you. 

This publication could include technical inaccuracies or typographical errors. Changes are periodically made 
to the infonnation herein; these changes will be incorporated in new editions of the publication. IBM may 
make improvements and/or changes in the product(s) and/or the program(s) described in this publication at 
any time. 

This publication was developed for products and services offered in the United States of America. IBM may 
not offer the products, services, or features discussed in this document in other countries, and the information 
is subject to change without notice. Consult your local IBM representative for information on the products, 
services, and features available in your area. 

Requests for technical infonnation about IBM products should be made to your IBM reseller or IBM 
marketing representative. 


Copyright Notices 

COPYRIGHT LICENSE: This publication contains printed sample application programs in source 
language, which illustrate OS/2 programming techniques. You may copy, modify, and distribute these sample 
programs in any form without payment to IBM, for the purposes of developing, using, marketing or 
distributing application programs conforming to the OS/2 application programming interface. 

Each copy of any portion of these sample programs or any derivative work, which is distributed to others, 
must include a copyright notice as follows: "© (your company name) (year). All rights reserved." 
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Note to U.S. Government Users: Documentation related to restricted rights - use, duplication or disclosure is 
subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp. 


Disclaimers 

References in this publication to IBM products, programs, or services do not imply that IBM intends to make 
these available in all countries in which IBM operates. Any reference to an IBM product, program or service 
is not intended to state or imply that only that IBM product, program, or service may be used. Subject to 
IBM's valid intellectual property or other legally protectable rights, any functionally equivalent product, 
program, or service may be used instead of the IBM product, program, or service. The evaluation and 
verification of operation in conjunction with other products, except those expressly designated by IBM, are 
the responsibility of the user. 

IBM may have patents or pending patent applications covering subject matter in this document. The 
furnishing of this document does not give you any license to these patents. You can send license inquiries, in 
writing, to: 

IBM Director of Licensing 
IBM Corporation 
500 Columbus Avenue 
Thomwood, NY 10594 
U.S. A. 

Asia-Pacific users can inquire, in writing, to the IBM Director of Intellectual Property and Licensing, IBM 
World Trade Asia Corporation, 2-31 Roppongi 3-chome, Minato-ku, Tokyo 106, Japan. 

Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange 
of information between independently created programs and other programs (including this one) and (ii) the 
mutual use of the information which has been exchanged, should contact IBM Corporation, Department 
LZKS, 1 1400 Burnet Road, Austin, TX 78758 U.S. A. Such infonnation may be available, subject to 
appropriate terms and conditions, including in some cases, payment of a fee. 

The following terms are trademarks of the IBM Corporation in the United States or other countries or both: 
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OS/2 

The following terms are trademarks of other companies: 

Microsoft, Windows, Windows NT®, and the Windows 95 logo are trademarks or registered trademarks of 
Microsoft Corporation. 

Other company, product, and service names, which may be denoted by a double asterisk (**), may be 
trademarks or service marks of others. 
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